# IDEA.md – an explorer of your own for Azure Service Bus This is a self-contained brief. Give it in full to Claude Code (or a similar tool) to build an implementation of your own. It draws on what was learned building Service Bus Explorer, an app for Windows and macOS written in Rust with Claude Code. ## 1. What to build A desktop app for exploring Azure Service Bus – a faster alternative to the portal's Service Bus Explorer, and a counterpart to Paolo Salvatori's Windows program that also works on macOS. The app must be able to: - **save several namespaces locally**, grouped (Prod, Test …), with a connection string or Entra ID (`az login`), a production flag and a read-only mode per namespace - show **queues, topics and subscriptions in a tree** with active messages and dead letters on every row; dead letters in a warning colour, topics summing their subscriptions; a filter, manual and automatic refresh - an **overview per namespace** with the most dead letters first - show the **configuration** of each entity (lock duration, TTL, max delivery count, sessions, duplicate detection, forward-to, status, size, all counts) and the subscriptions' **rules** (SQL filter, correlation filter, action), and the namespace info - **browse messages and dead letters** with true peek, page by page, with search; a table with sequence number, id, time, subject, size and for dead letters the reason and description; a detail panel with the body (JSON and XML formatted) and all properties with their types; copying - **resubmit or delete** selected dead letters, **purge** a queue, **send** new messages and **export** to JSON **Not** included: editing properties, creating or deleting entities, discovering namespaces in the Azure subscription automatically, editing a message before it's resubmitted, charts over time. ## 2. Stack and architecture What **matters** is marked; the rest can be swapped. - **Rust**, a workspace with a core without an interface (`core`: namespaces, sign-in, management API, messages) and the app (eframe/egui). - **Important: networking on its own tokio runtime in the core, never on the UI thread.** Every call is a task the app checks every frame. - **Management (counts, properties, rules) with a REST client of your own** – there's no Rust library. `GET https://{ns}.servicebus.windows.net/$Resources/queues?api-version=2021-05&$skip=0&$top=100`, the same for topics, subscriptions, rules and `$namespaceinfo`, in pages of 100 until a page isn't full. Authentication with SAS (HMAC-SHA256 of the URL-encoded resource and the expiry, with the key's text) or `Bearer` with the scope `https://servicebus.azure.net/.default`. - **Messages over AMQP** with `azservicebus`: peek from a sequence number, the dead-letter subqueue, receive-and-delete and send. Switch to Microsoft's official crate when the AMQP version is published. - **TLS with native-tls**: the system certificate store on both platforms, so company CAs work, and no C crypto that needs the Windows SDK headers when cross-compiling. - **Entra ID by running `az account get-access-token`** yourself, with your own search for `az`. - Namespaces in a local file with permissions 0600. With Entra ID there's no secret in it. ## 3. Decisions that turned out to matter **The counts in the tree.** Active and dead letters on every row, dead letters in a warning colour and summed per topic. The single most useful thing, according to every tool that has it. **True peek, never peek-lock.** Use `com.microsoft:peek-message` from a sequence number. Locking and abandoning a message to show it raises DeliveryCount – looking must never change anything. **The body is opaque bytes when resubmitting.** The properties keep their AMQP types. Only the broker's annotations and DeadLetterReason/-Description are removed. The model's issue tracker has reports of lost SessionIds, extra quotes, new line endings and broken UTF-8. **Resubmitting from a subscription goes to the topic**, and so reaches every subscription whose rules let the message through. The confirmation should say so. **Everything that takes time runs in the background**, with progress and Cancel. Purging a queue stops at the count when it started, so it doesn't eat new messages. **Care in production.** Everything that changes something is confirmed with namespace, entity, queue and target. In production: a red frame around the workspace and the entity's name to type. Read-only turns off everything that changes things. **Show .NET types as values.** The .NET SDK encodes `DateTimeOffset` as `com.microsoft:datetime-offset` with ticks since year 1, and has its own types for time spans and URIs. Show them as a time, a time span and an address, not as raw AMQP values. **Test against Microsoft's emulator in Docker**, and try anything destructive only there – never against a real namespace. Tests never read the user's namespaces: the app gets a file of its own. **Developer hooks from day one**: `_CONFIG_DIR`, `_SCREENSHOT=file.png` from the real window, and a test without a window that renders against the emulator in different states (overview, rules, messages, dialogs, the production confirmation). ## 4. Pitfalls - **An incomplete page doesn't mean the queue is done.** Service Bus doesn't always fill a peek page – the broker limits the response size, and a partitioned entity answers from one partition at a time. Ask again until the page is full or a response comes back empty. - **In a partitioned entity the sequence numbers in a response don't rise.** Continue after the *last* message in the response, not after the highest number. - **The emulator gives no detailed counts.** Queues lack `CountDetails`, the subscriptions' have garbled names and `MessageCount` is 0. Test the counts against a saved response in Azure's shape, and show `–` for unknown counts. - **The emulator doesn't check SAS keys**, and a freshly dead-lettered message shows up in peek only after a few hundred milliseconds. - **An entity that doesn't exist gives an empty feed**, not a 404. - **`CountDetails` has children in another XML namespace.** Match on the local name. - **A GUI app doesn't have the shell's `PATH`.** From Finder, the Dock or the Start menu, `az` isn't found. Look in known places. - **No screenshot arrives while the screen is asleep** – keep a rendering without a window as a fallback. ## 5. Requirements and measurements - The tree and the overview refresh without the interface stalling, even with many entities. - Peek never changes DeliveryCount – tested against the emulator. - A resubmitted body is byte for byte the same as the original. - Service Bus Explorer has around 70 tests in the core and the app, plus the tests against the emulator. ## 6. How it's verified - `cargo clippy --workspace --all-targets` with no warnings, `cargo test --workspace` and `cargo check` for Windows. - **Tests against the emulator** whenever something in the networking changes: peek, dead letters, resubmit, delete, purge, send, rules. - **The counts against a saved response** in the same shape as Azure's. - **UI tests without a window** and **screenshots** of every new view against the emulator. - What needs a real namespace and a real sign-in becomes a verification task with a checklist – and is tried in read-only mode. ## 7. Way of working - **Research first**: Salvatori's Service Bus Explorer, the portal's, Turbo360, PurpleExplorer, CrossBusExplorer, ServicebusBrowser and the Rust terminal tools – and their issue trackers. Mark what was checked against a source and what is judgement. - **Ask about the real decisions**: where connection strings should be stored, how careful the app should be in production. - **One task at a time**, with the measurement in the closing comment. ## 8. The prompt > Build a desktop app for [Windows and macOS] in [Rust with eframe/egui] to explore Azure Service Bus: several saved namespaces with a connection string or Entra ID, queues, topics and subscriptions in a tree with counts and dead letters, the configuration and rules, peek in messages and dead letters, and resubmit, delete and purge with extra care in production. > > Read all of IDEA.md below first. It describes the features, the architecture, the decisions that turned out to matter and the pitfalls to avoid. > > Work like this: > 1. Research similar programs and their issue trackers, and write a plan split into tasks. Ask me about the decisions that are mine. > 2. Run networking on its own runtime, never on the UI thread. > 3. Use true peek, and resubmit the body byte for byte. > 4. Test against the Service Bus emulator and never try anything destructive against my real namespaces. > 5. Leave what needs my real namespaces as a checklist for me. > > [paste IDEA.md here]