# IDEA.md – en egen utforskare för Azure Service Bus Det här är en fristående uppdragsbeskrivning. Ge den i sin helhet till Claude Code (eller ett liknande verktyg) för att bygga en egen implementation. Den bygger på det som lärdes när Service Bus Explorer byggdes, en app för Windows och macOS skriven i Rust med Claude Code. ## 1. Vad som ska byggas En skrivbordsapp för att utforska Azure Service Bus – ett snabbare alternativ till portalens Service Bus Explorer, och en motsvarighet till Paolo Salvatoris Windows-program som också fungerar på macOS. Appen ska kunna: - **spara flera namespaces lokalt**, grupperade (Prod, Test …), med anslutningssträng eller Entra ID (`az login`), produktionsmarkering och ett läge för bara läsning per namespace - visa **köer, topics och prenumerationer i ett träd** med aktiva meddelanden och dead letters på varje rad; dead letters i varningsfärg, topics som summerar sina prenumerationer; filter, uppdatering för hand och automatiskt - en **översikt per namespace** med flest dead letters först - visa **konfigurationen** för varje entitet (lock duration, TTL, max delivery count, sessioner, dubblettdetektering, forward-to, status, storlek, alla antal) och prenumerationernas **regler** (SQL-filter, korrelationsfilter, action), och namespacets info - **bläddra i meddelanden och dead letters** med äkta peek, sida för sida, med sökning; tabell med sekvensnummer, id, tid, subject, storlek och för dead letters orsak och beskrivning; detaljpanel med kroppen (JSON och XML formaterade) och alla egenskaper med typer; kopiering - **skicka om eller ta bort** valda dead letters, **tömma** en kö, **skicka** nya meddelanden och **exportera** till JSON **Ingår inte**: ändra egenskaper, skapa eller ta bort entiteter, hitta namespaces i Azure-prenumerationen automatiskt, ändra ett meddelande innan det skickas om, diagram över tid. ## 2. Stack och arkitektur Det som **spelar roll** är markerat; resten går att byta. - **Rust**, en workspace med en kärna utan gränssnitt (`core`: namespaces, inloggning, management-API, meddelanden) och appen (eframe/egui). - **Viktigt: nätverket på en egen tokio-runtime i kärnan, aldrig i gränssnittstråden.** Varje anrop är en uppgift som appen läser av varje bildruta. - **Management (antal, egenskaper, regler) med en egen REST-klient** – det finns inget Rust-bibliotek. `GET https://{ns}.servicebus.windows.net/$Resources/queues?api-version=2021-05&$skip=0&$top=100`, likadant för topics, prenumerationer, regler och `$namespaceinfo`, sidor om 100 tills en sida inte är full. Autentisering med SAS (HMAC-SHA256 av den url-kodade resursen och utgångstiden, med nyckelns text) eller `Bearer` med scopet `https://servicebus.azure.net/.default`. - **Meddelandena över AMQP** med `azservicebus`: peek från ett sekvensnummer, dead-letter-subkön, receive-and-delete och send. Byt till Microsofts officiella crate när AMQP-versionen publiceras. - **TLS med native-tls**: systemets certifikatlager på båda plattformarna, så att företags-CA:er fungerar, och inget C-krypto som kräver Windows SDK:ns headers vid korskompilering. - **Entra ID genom att köra `az account get-access-token`** själv, med egen sökning efter `az`. - Namespaces i en lokal fil med rättigheterna 0600. Med Entra ID står ingen hemlighet i den. ## 3. Beslut som visade sig avgörande **Antalen i trädet.** Aktiva och dead letters på varje rad, dead letters i varningsfärg och summerade per topic. Det enskilt mest användbara, enligt alla verktyg som har det. **Äkta peek, aldrig peek-lock.** Använd `com.microsoft:peek-message` från ett sekvensnummer. Att låsa och släppa ett meddelande för att visa det höjer DeliveryCount – att titta ska aldrig ändra något. **Kroppen är opaka bytes vid omsändning.** Egenskaperna behåller sina AMQP-typer. Bara mäklarens annoteringar och DeadLetterReason/-Description tas bort. Förebildens ärendelista har rapporter om tappade SessionId, extra citattecken, nya radslut och trasig UTF-8. **Omsändning från en prenumeration går till topicen**, och når då alla prenumerationer vars regler släpper igenom meddelandet. Bekräftelsen ska säga det. **Allt som tar tid går i bakgrunden**, med förlopp och Avbryt. Att tömma en kö stannar vid antalet när det startade, så att det inte äter nya meddelanden. **Försiktighet i produktion.** Allt som ändrar något bekräftas med namespace, entitet, kö och mål. I produktion: en röd ram runt arbetsytan och entitetens namn som måste skrivas in. Bara läsning stänger av allt som ändrar. **Visa .NET-typer som värden.** .NET-SDK:n kodar `DateTimeOffset` som `com.microsoft:datetime-offset` med tick sedan år 1, och har egna typer för tidsspann och adresser. Visa dem som tid, tidsspann och adress, inte som råa AMQP-värden. **Testa mot Microsofts emulator i Docker**, och prova allt destruktivt bara där – aldrig mot ett riktigt namespace. Tester läser aldrig användarens namespaces: appen får en egen fil. **Utvecklarkrokar från dag ett**: `_CONFIG_DIR`, `_SCREENSHOT=fil.png` från det riktiga fönstret, och ett test utan fönster som renderar mot emulatorn i olika lägen (översikt, regler, meddelanden, dialoger, produktionsbekräftelsen). ## 4. Fallgropar - **En ofullständig sida betyder inte att kön är slut.** Service Bus fyller inte alltid en peek-sida – mäklaren begränsar svarets storlek, och en partitionerad entitet svarar ur en partition i taget. Fråga igen tills sidan är full eller ett svar kommer tomt. - **I en partitionerad entitet stiger inte sekvensnumren** i ett svar. Fortsätt efter det *sista* meddelandet i svaret, inte efter det högsta numret. - **Emulatorn ger inga uppdelade antal.** Köer saknar `CountDetails`, prenumerationernas har förvrängda namn och `MessageCount` är 0. Pröva antalen mot ett sparat svar i Azures form, och visa `–` för okända antal. - **Emulatorn kontrollerar inte SAS-nycklar**, och ett nyss dead-lettrat meddelande syns i peek först efter några hundra millisekunder. - **En entitet som inte finns ger ett tomt flöde**, inte 404. - **`CountDetails` har barn i en annan XML-namnrymd.** Matcha på lokalt namn. - **En GUI-app har inte skalets `PATH`.** Från Finder, Dock eller Startmenyn hittas inte `az`. Leta på kända ställen. - **Skärmbilder kommer inte om skärmen sover** – ha en rendering utan fönster som reserv. ## 5. Krav och mätningar - Trädet och översikten uppdateras utan att gränssnittet stannar, även med många entiteter. - Peek ändrar aldrig DeliveryCount – prövat mot emulatorn. - En omsänd kropp är byte för byte densamma som originalets. - Service Bus Explorer har runt 70 tester i kärnan och appen, plus testerna mot emulatorn. ## 6. Så verifieras det - `cargo clippy --workspace --all-targets` utan varningar, `cargo test --workspace` och `cargo check` för Windows. - **Tester mot emulatorn** när något i nätverksdelen ändrats: peek, dead letters, omsändning, borttagning, tömning, skicka, regler. - **Antalen mot ett sparat svar** i samma form som Azures. - **UI-tester utan fönster** och **skärmbilder** av varje ny vy mot emulatorn. - Det som kräver ett riktigt namespace och en riktig inloggning blir ett verifieringsärende med en checklista – och provas i läget bara läsning. ## 7. Arbetssätt - **Research först**: Salvatoris Service Bus Explorer, portalens, Turbo360, PurpleExplorer, CrossBusExplorer, ServicebusBrowser och Rust-verktygen i terminalen – och deras ärendelistor. Markera vad som är kontrollerat mot en källa och vad som är bedömning. - **Fråga om de verkliga besluten**: var anslutningssträngarna ska sparas, hur försiktig appen ska vara i produktion. - **Ett ärende i taget**, med mätningen i den avslutande kommentaren. ## 8. Prompten > Bygg en skrivbordsapp för [Windows och macOS] i [Rust med eframe/egui] för att utforska Azure Service Bus: flera sparade namespaces med anslutningssträng eller Entra ID, köer, topics och prenumerationer i ett träd med antal och dead letters, konfigurationen och reglerna, peek i meddelanden och dead letters, och omsändning, borttagning och tömning med extra försiktighet i produktion. > > Läs hela IDEA.md nedan först. Den beskriver funktionerna, arkitekturen, de beslut som visade sig avgörande och fallgroparna att undvika. > > Arbeta så här: > 1. Gör research på liknande program och deras ärendelistor, och skriv en plan uppdelad i ärenden. Fråga mig om det som är mina beslut. > 2. Kör nätverket på en egen runtime, aldrig i gränssnittstråden. > 3. Använd äkta peek, och skicka om kroppen byte för byte. > 4. Testa mot Service Bus-emulatorn och prova aldrig något destruktivt mot mina riktiga namespaces. > 5. Lämna det som kräver mina riktiga namespaces som en checklista åt mig. > > [klistra in IDEA.md här]