backend-api

# Backend API Development Guide ## Extension API: @podman-desktop/api The backend runs as a Podman Desktop extension in Node.js. All host interactions go through `@podman-desktop/api`, which is provided by the Podman Desktop runtime (not bundled — it's an external dependency). ```typescript import * as extensionApi from '@podman-desktop/api'; ``` ### Check API API signatures change across versions. Read the installed types directly: 1. **Full API types**: Read `node_modules/@podman-desktop/api/index.d.ts` 2. **Current RPC contract**: Read `packages/shared/src/BootcAPI.ts` 3. **Current models**: Read files in `packages/shared/src/models/` 4. **Current messages**: Read `packages/shared/src/messages/Messages.ts` 5. **See existing usage**: `grep -r "extensionApi\." packages/backend/src/` Always verify method signatures against the actual type definitions before using them. ## RPC Architecture Frontend ↔ Backend communication uses a typed RPC proxy over webview `postMessage`. ### Adding a New API Method **Step 1: Define in shared contract** (`packages/shared/src/BootcAPI.ts`): ```typescript export abstract class BootcApi { // ... existing methods abstract myNewMethod(param: string): Promise<ResultType>; } ``` **Step 2: Implement in backend** (`packages/backend/src/api-impl.ts`): ```typescript export class BootcApiImpl extends BootcApi { async myNewMethod(param: string): Promise<ResultType> { const result = await extensionApi.containerEngine.listImages(); return transformResult(result); } } ``` **Step 3: Call from frontend** (automatic — RPC proxy exposes all methods): ```typescript import { bootcClient } from '/@/api/client'; const result = await bootcClient.myNewMethod('value'); ``` ### RPC Timeout Default timeout is 5 seconds per RPC call. For long-running operations, add the method name to the no-timeout list: ```bash cat packages/shared/src/messages/NoTimeoutChannels.ts ``` ### Sending Notifications (Backend → Frontend) Push data to the frontend via message IDs. See the current messages: ```bash cat packages/shared/src/messages/Messages.ts ``` Send from backend: ```typescript this.panel.webview.postMessage({ id: Messages.MSG_HISTORY_UPDATE, body: data }); ``` Frontend subscribes via RPC: ```typescript import { rpcBrowser } from '/@/api/client'; rpcBrowser.subscribe(Messages.MSG_NAVIGATE_BUILD, (path: string) => { router.goto(`/disk-images/build/${path}`); }); ``` ## Discovering APIs APIs change across versions. Always read the source rather than relying on memory. ### @podman-desktop/api ```bash # Full API surface — the single source of truth cat node_modules/@podman-desktop/api/index.d.ts # Find how specific APIs are already used in this codebase grep -rn "extensionApi\.\(containerEngine\|window\|provider\|navigation\|configuration\|process\|env\)" packages/backend/src/ ``` ### Internal helpers ```bash # Key backend modules — read these to find available helpers ls packages/backend/src/*.ts ls packages/shared/src/models/ ``` ## Checklist: Adding a New Backend Feature 1. Add abstract method to `packages/shared/src/BootcAPI.ts` 2. Implement in `packages/backend/src/api-impl.ts` 3. If long-running (>5s), add to `NoTimeoutChannels.ts` 4. If it pushes data to frontend, add a message to `Messages.ts` 5. Add types/models in `packages/shared/src/models/` if needed 6. Add telemetry for usage and errors 7. Write unit tests mocking `@podman-desktop/api` 8. Frontend can call via `bootcClient.myNewMethod()` — no wiring needed