diff --git a/src/core/driver-catalog.ts b/src/core/driver-catalog.ts index 2ede11607..ac6187f67 100644 --- a/src/core/driver-catalog.ts +++ b/src/core/driver-catalog.ts @@ -14,7 +14,6 @@ import type { DeviceInput, UnavailableDeviceInput } from "./input.js"; import { type ScreenFeed, ScreenNotSupportedError, type ScreenSettings } from "./screen.js"; import { stableError } from "./stable-error.js"; -/** Thrown when no installed driver can serve the requested platform. */ export class NoDriverError extends Error { constructor(readonly platform: Platform) { super(`No driver registered for platform: ${platform}`); @@ -22,7 +21,6 @@ export class NoDriverError extends Error { } } -/** Thrown when no registered driver answers to the requested `simlock ` wrapper. */ export class UnknownPassthroughToolError extends Error { constructor(readonly tool: string) { super(`No driver provides a ${tool} passthrough`); @@ -30,18 +28,12 @@ export class UnknownPassthroughToolError extends Error { } } -/** - * The model names to try for each class, per platform, most preferred first: the operator's own - * list followed by the driver's built-in one (ADR 0015 §4). Built once, by the composition root. - */ export type ModelPreferences = Readonly< Partial>>>> >; -/** One registered driver's catalog entry, tagged with its platform. */ export interface PlatformCatalog extends DriverCatalogEntry { readonly platform: Platform; - /** ADR 0015 §4: the model Simlock would create for each class on this host. */ readonly classDefaults: Readonly>>; } @@ -50,7 +42,6 @@ export interface ScreenAvailability { readonly reason?: string; } -/** Immutable platform-to-driver lookup used by the lease path. */ export class DriverCatalog { readonly #drivers: ReadonlyMap; readonly #logger: Logger; @@ -74,12 +65,6 @@ export class DriverCatalog { return driver; } - /** - * Routes `simlock ` to whichever driver claims that tool name. Routing is - * all this does: which flag scopes the tool, which verbs it refuses, and what its - * environment must carry are decided inside the driver, so a third driver can add a - * wrapper without a line changing here (architecture rules 2 and 3). - */ async passthrough( tool: string, device: VirtualDriverDevice | PhysicalDriverDevice | undefined, @@ -139,14 +124,6 @@ export class DriverCatalog { return this.get(request.platform).resolveSpec(request); } - /** - * Aggregates catalogs across every registered driver, or just the given - * platform. A platform with no registered driver (its SDK is missing) is - * omitted rather than raising `NoDriverError` — mirrors `discoverDrivers`. - * Across platforms, a driver whose catalog rejects is left out and logged and - * the others are still listed; with one platform named, its rejection is the - * answer. - */ async listCatalog(platform?: Platform): Promise { const listed = await Promise.all( this.select(platform).map(async (driver): Promise => { @@ -170,12 +147,6 @@ export class DriverCatalog { return listed.filter((entry) => entry !== undefined); } - /** - * For each class, the model Simlock would create on this host (ADR 0015 §4): of the names on - * the class's preference list that the entry lists and that are of that class, the first that - * pairs with an installed runtime, else the first of them. A class in which no name counts has - * no entry. - */ #classDefaults( platform: Platform, entry: DriverCatalogEntry, @@ -193,10 +164,6 @@ export class DriverCatalog { return defaults; } - /** - * Every registered driver, or only the given platform's. A platform with no registered driver - * gives none rather than raising `NoDriverError`: a read across platforms leaves it out. - */ select(platform?: Platform): readonly Driver[] { if (platform === undefined) return [...this.#drivers.values()]; const driver = this.#drivers.get(platform); diff --git a/src/core/fake-driver.ts b/src/core/fake-driver.ts index 462ae8c9a..a292d5cc8 100644 --- a/src/core/fake-driver.ts +++ b/src/core/fake-driver.ts @@ -87,45 +87,17 @@ export interface FakeDriverOptions { readonly removalResidue?: string; readonly deviceRoot?: string; readonly estimateMs?: Partial>; - /** - * Reclaim estimate for a `full` clean, when a test needs the two clean levels priced apart - * the way a real driver prices them (an Android `snapshot` against a `wipe`). Falls back to - * `estimateMs.reclaim`, so a test that does not care about the split says nothing. - */ readonly fullCleanReclaimEstimateMs?: number; - /** - * The `DriverDevice.mode` `makeReady` reports for every boot, overriding what it would - * otherwise report -- settable by a test that needs a slim pass that did not happen, or the - * core's `mode` persistence without a real iOS driver. - */ readonly mode?: DeviceMode | undefined; - /** - * The OS versions this fake can slim. A slim request on one of them resolves to a slim spec, - * and a prepare boot of a slim-spec device reports `"slim"`. Absent or empty: this fake knows - * nothing of modes, like every real driver but iOS, and every request resolves to a full spec. - */ readonly slimmableOsVersions?: readonly string[]; readonly knownModels?: readonly string[]; - /** - * What `listCatalog` reports a model pairs with. A model left out pairs with every available - * version, which is also the default for every model. - */ readonly modelRuntimes?: Readonly>; - /** What `listCatalog` reports as other names per model; none unless a test says otherwise. */ readonly modelAliases?: Readonly>; - /** The built-in preference lists the driver carries, per class; none unless a test says otherwise. */ readonly defaultModels?: Readonly>>; - /** What `listCatalog` reports as each model's class; empty unless a test says otherwise. */ readonly modelClasses?: Readonly>; - /** - * What `listCatalog` reports as installed images; the field is absent unless set. A request - * naming an image tag resolves only to a runtime listed here with that tag. - */ readonly images?: readonly DriverCatalogImage[]; - /** What `listCatalog` reports as custom models; the field is absent unless set. */ readonly customModels?: readonly string[]; readonly latencyMs?: Partial>; - /** What a grant for this driver's devices should carry; empty unless a test says otherwise. */ readonly leaseEnvironment?: Readonly>; /** why: absent by default, so two fakes in one catalog do not both answer to the same tool. */ readonly passthroughTools?: readonly string[]; @@ -138,11 +110,6 @@ export interface FakeDriverOptions { context?: PassthroughContext, ) => PassthroughCommand; readonly platform: Platform; - /** - * What this driver claims to find outside its root for a given device id, keyed by - * `driverDeviceId`. Empty by default: a driver that has never had a pre-root life finds - * nothing, which is what keeps every other test's missing device simply missing. - */ readonly legacyDevices?: Readonly>; readonly reclaimResult?: "ready" | "shutdown"; readonly reclaimStrategy?: "erase" | "snapshot" | "wipe"; @@ -207,7 +174,6 @@ export class FakeDriver implements Driver { readonly #reclaimStrategy: "erase" | "snapshot" | "wipe"; readonly #devices = new Map(); readonly #legacyDevices: Map; - /** Bumped on every `makeReady` boot -- mirrors a real driver reassigning a port per boot. */ readonly #bootCounts = new Map(); readonly #addressIsDeviceId: boolean; #managedReality: DriverReality | undefined; @@ -263,11 +229,6 @@ export class FakeDriver implements Driver { return this.#defaultModels ?? {}; } - /** - * Succeeds unless a test fails it through `failOn`. A real driver re-runs the filesystem - * checks here; the fake only has to be refusable, since what `Doctor` does with a refusal - * is the behaviour under test. - */ async revalidateRoot(): Promise { await this.#beforeCall("revalidateRoot"); } @@ -282,7 +243,6 @@ export class FakeDriver implements Driver { this.#legacyDevices.delete(device.deviceId); } - /** Never installs: a version that is not available throws, naming it as the component. */ async resolveSpec(request: ExactDeviceRequest): Promise { await this.#beforeCall("resolveSpec", request); this.#assertMatchingPlatform(request.platform); @@ -308,7 +268,6 @@ export class FakeDriver implements Driver { }; } - /** Defaults to the newest available version; a missing one fails, naming it as the component. */ #resolveOsVersion(requested: string | undefined): string { const osVersion = requested ?? newestVersion(this.#availableOsVersions); if (osVersion === undefined) { @@ -320,10 +279,6 @@ export class FakeDriver implements Driver { return osVersion; } - /** - * A version with a scripted image (`images`) of `imageTag`: the requested one, or else the - * newest. None fails naming no component, so a tagged request is never offered a download. - */ #resolveTaggedOsVersion(requested: string | undefined, imageTag: string): string { const tagged = new Set( (this.#images ?? []).filter((image) => image.tag === imageTag).map((image) => image.runtime), @@ -335,18 +290,11 @@ export class FakeDriver implements Driver { return osVersion; } - /** `"latest"` is not a version, so it is never found here -- only an install run can tell. */ async findComponent(component: string): Promise { await this.#beforeCall("findComponent", component); return this.#installed(component); } - /** - * Makes `component` available and logs the call. `"latest"` is the newest available version, - * or a version called `latest` when there is none. Scripted through `failOn("installComponent", - * n, error)`, `holdInstalls()` (it then waits for `releaseInstalls()` or its signal) and the - * `installProgress` option. - */ async installComponent( component: string, options: { @@ -370,21 +318,11 @@ export class FakeDriver implements Driver { return { outcome: "installed", receipt, version }; } - /** - * One entry per available version, with the receipt `findComponent` and `installComponent` - * report for it, and the scripted size and foreign devices. - */ async listComponents(): Promise { await this.#beforeCall("listComponents"); return this.#listedComponents(); } - /** - * Removes the available version whose receipt this is, through the same steps every driver - * takes (`removeListedComponent`), reading the same listing `listComponents` answers. Scripted - * through `failOn("removeComponent", n, error)`, `holdRemovals()` (it then waits for - * `releaseRemovals()` or its signal) and the `removalResidue` option. - */ async removeComponent( receipt: ComponentReceipt, options: { readonly signal: AbortSignal }, @@ -474,12 +412,6 @@ export class FakeDriver implements Driver { }; } - /** - * Each boot re-reads a fresh address, same as the real drivers -- never the caller's. - * `options` is recorded on the call log (`calls`) so a test can assert what a caller passed. - * A slimming fake (`slimmableOsVersions`) reports `"slim"` for a prepare boot of a slim-spec - * device and nothing on a recover boot, as the iOS driver does; the `mode` option overrides it. - */ async makeReady( device: DriverDevice, options: { readonly purpose: "prepare" | "recover"; readonly mode: DeviceMode }, @@ -695,7 +627,7 @@ export class FakeDriver implements Driver { } /** - * Stages what `listManaged` reports. Everything passed in is reported back, name and + * why: Stages what `listManaged` reports. Everything passed in is reported back, name and * all: a real driver answers from what sits inside the root it owns, so a double that * screened entries by prefix would be modelling ownership Simlock stopped inferring * (safety rule 8). @@ -747,7 +679,7 @@ export class FakeDriver implements Driver { } } -/** One 30 s read limit plus one 60 s uninstall limit: what the real physical drivers will answer. */ +/** why: One 30 s read limit plus one 60 s uninstall limit: what the real physical drivers will answer. */ const PHYSICAL_RECLAIM_ESTIMATE_MS = 90_000; function preinstalledReceipts(versions: ReadonlySet): Map { diff --git a/src/core/testing.ts b/src/core/testing.ts index bcb69dc8b..6f9e7ddf4 100644 --- a/src/core/testing.ts +++ b/src/core/testing.ts @@ -21,7 +21,7 @@ import { warmPoolOwner } from "./warm-pool/index.js"; import { SerializedDecision } from "./serialized-decision.js"; /** - * Test-only: fakes and test wiring other modules' tests use. Only a `*.test.ts` file or a + * why: Test-only: fakes and test wiring other modules' tests use. Only a `*.test.ts` file or a * `test-*.ts` helper may import this file, and `pnpm lint` enforces it. Anything production code * also uses belongs on `index.ts`. */ @@ -37,12 +37,6 @@ export { FakeDriver, fakeDeviceDataTable } from "./fake-driver.js"; export type { FakeDriverOptions } from "./fake-driver.js"; export { QuarantineCoordinator } from "./quarantine-coordinator.js"; -/** - * Test-only: the decision gate and the component installer `createCore` and `createLeasing` are - * built with, wired the way the daemon wires them -- one gate shared by both and the installer, so the - * installer's registry writes are serialized with every other one. Unlimited free disk. A test - * that passes its own `components` gets the gate alone. - */ export function testComponentWiring< Components extends Pick = ComponentInstaller, >(options: { @@ -50,7 +44,6 @@ export function testComponentWiring< readonly drivers: readonly Driver[]; readonly eventBus: Pick; readonly registry: Pick; - /** Stands in for the installer, when a test needs to see whether it was reached at all. */ readonly components?: Components | undefined; }): { readonly components: Components | ComponentInstaller; diff --git a/src/drivers/android/index.ts b/src/drivers/android/index.ts index 6361603a3..054e12b8b 100644 --- a/src/drivers/android/index.ts +++ b/src/drivers/android/index.ts @@ -353,7 +353,7 @@ function allowedGlobalArity(argument: string): "none" | "value" | undefined { if (argument === "-d" || argument === "-e") return "none"; if (argument === "-s") return "value"; if (argument === "-t") return "value"; - if (argument.startsWith("-t") && argument.length > 2) return "none"; // fused, e.g. `-t123` + if (argument.startsWith("-t") && argument.length > 2) return "none"; return undefined; } diff --git a/src/gateway/index.ts b/src/gateway/index.ts index 4d8c2a4b8..f88e91040 100644 --- a/src/gateway/index.ts +++ b/src/gateway/index.ts @@ -1,5 +1,5 @@ /** - * `src/gateway` -- the second implementation of the daemon contract (ADR 0005 §32), for a + * why: `src/gateway` -- the second implementation of the daemon contract (ADR 0005 §32), for a * daemon that owns no devices and fronts the workers connected to it. * * Boundaries (§33, enforced by `pnpm lint`): nothing here imports `src/drivers`, and diff --git a/src/http/app.ts b/src/http/app.ts index 5160a0852..10335f28b 100644 --- a/src/http/app.ts +++ b/src/http/app.ts @@ -84,7 +84,7 @@ import { } from "./tracker.js"; /** - * The device fields the lease routes read: what a lease payload is built from, plus two that + * why: The device fields the lease routes read: what a lease payload is built from, plus two that * only one kind of daemon has. A worker's own registry record carries `state`, which `DELETE * /v1/leases/:id` reports; a gateway holds no device state of its own and leaves it out rather * than inventing one. A gateway's device carries the `workerId` it lives on, because a device @@ -95,10 +95,6 @@ export interface HttpRegistryDevice extends HttpLeaseDevice { readonly workerId?: string; } -/** Minimal structural read surface -- narrower than importing the `Registry` class itself. Kept - * for the one thing dispatcher operations don't hand back: a device record for a specific - * lease's `GET /v1/leases/:id` decoration (there is no per-id device operation). A worker - * passes its registry; a gateway passes the devices its worker views hold in the grant shape. */ export interface HttpRegistryReader { readonly snapshot: { readonly devices: readonly HttpRegistryDevice[]; @@ -106,22 +102,16 @@ export interface HttpRegistryReader { } export interface HttpGatewayDeps { - /** ADR 0003 §2: the exact same shared `Dispatcher` the socket path uses -- see - * `dispatcher-session.ts`'s `HttpDispatch`. */ readonly dispatch: HttpDispatch; readonly registry: HttpRegistryReader; - /** The daemon's stored lease requests: a worker's request book, or a gateway's. */ readonly leaseRequests: LeaseRequestReader; readonly eventBus: EventBus; - /** ADR §8: fed to `LeaseNoticeBuffer` instead of it subscribing to `eventBus` itself. */ readonly ownerRoutedFacts: OwnerRoutedFacts; readonly clock: Clock; readonly idGenerator: IdGenerator; readonly logger: Logger; readonly config: Config; readonly auth: Pick; - /** `false` on a gateway, which never downloads: `allowDownload` then does not answer the lease - * request `POST` early. Default `true`. */ readonly answerDownloadsEarly?: boolean | undefined; readonly mounts?: readonly HttpMount[]; readonly leaseRoutes?: readonly HttpLeaseRoute[]; @@ -168,7 +158,6 @@ export interface HttpMount { type Env = AuthEnv; -/** Upper bound on `?wait=` long-polls; bounds how long an abandoned poll can pin resources. */ const MAX_LONG_POLL_SECONDS = 60; function toLeaseRequestInput(body: z.infer): LeaseRequestInput { @@ -222,7 +211,7 @@ export function createHttpApp(deps: HttpGatewayDeps): OpenAPIHono & HttpApp const agentAuth = requireAuth(deps.auth); - // The one error boundary. Hono's `compose` catches a thrown error at the layer that threw + // why: The one error boundary. Hono's `compose` catches a thrown error at the layer that threw // it and hands it to `app.onError` right there -- it never propagates up through an outer // middleware's own `await next()` -- so this has to be `onError`, not a try/catch here. app.onError((error, c) => { @@ -233,12 +222,10 @@ export function createHttpApp(deps: HttpGatewayDeps): OpenAPIHono & HttpApp return errorResponse(c, error); }); - // "One structured line per request outcome" -- by the time `next()` resolves, `onError` - // above has already run for a thrown error and `c.res` reflects the mapped status. app.use("*", async (c, next) => { const start = deps.clock.now(); await next(); - // The one unauthenticated route is also the one a tunnel/load-balancer polls: logging it + // why: The one unauthenticated route is also the one a tunnel/load-balancer polls: logging it // would let an anonymous flood drive the synchronous log sink from the event loop. if (c.req.path === "/v1/healthz") return; const identity = c.get("identity") as Identity | undefined; @@ -353,7 +340,7 @@ export function createHttpApp(deps: HttpGatewayDeps): OpenAPIHono & HttpApp const { wait } = c.req.valid("query"); if (wait !== undefined) { - // Clamped, not rejected: an oversized wait still long-polls correctly -- the client + // why: Clamped, not rejected: an oversized wait still long-polls correctly -- the client // simply re-polls sooner than it asked -- and the clamp bounds how long an abandoned // poll can pin its listener and timer. Aborting the request releases them immediately. await tracker.waitForChange( @@ -428,7 +415,7 @@ export function createHttpApp(deps: HttpGatewayDeps): OpenAPIHono & HttpApp const lease = await findOwnedLease(deps, session, c.req.valid("param").id); const device = findDevice(deps, lease); if (device === undefined) throw unknownLease(lease.id); - // ADR 0004: `ttlMs` comes off the lease record itself, so a payload served after a daemon + // why: ADR 0004: `ttlMs` comes off the lease record itself, so a payload served after a daemon // restart reports the lease's real width rather than a mode default standing in for a // per-request value this gateway no longer remembers. `requestId` is still gateway-side // bookkeeping, and is still the one field a restart can drop. @@ -475,7 +462,7 @@ export function createHttpApp(deps: HttpGatewayDeps): OpenAPIHono & HttpApp const identity = c.get("identity"); const leaseId = c.req.valid("param").id; const { requesterId, ...body } = c.req.valid("json"); - // Requester identity is the token's over HTTP, never the body's -- except for an + // why: Requester identity is the token's over HTTP, never the body's -- except for an // `operator` token, which is the proxying case `device.exec` reads it for. An agent // token that supplies one at all is refused, but by `device.exec`'s own `authorize` // hook (round 4, F4) rather than a route-level check: ADR 0003 §2 puts a contract @@ -502,8 +489,6 @@ export function createHttpApp(deps: HttpGatewayDeps): OpenAPIHono & HttpApp { leaseId, ...body, ...(requesterId === undefined ? {} : { requesterId }) }, buildHttpSession(identity, { onStarted: () => onStarted(), - // The relay's answer is this chunk's SSE write, and returning it is what stops - // the command while a client is not reading (ADR 0005 §19e). onOutput: (stream, chunk) => relay.push({ chunk, stream }), }), ) @@ -512,7 +497,7 @@ export function createHttpApp(deps: HttpGatewayDeps): OpenAPIHono & HttpApp (error: unknown) => ({ error, kind: "failed" }) as const, ); - // An SSE response cannot take back its status code, so the decision point is the moment + // why: An SSE response cannot take back its status code, so the decision point is the moment // the process exists: every failure that can precede one -- an unowned lease, an unknown // one, a refused verb, an unknown tool, a daemon still starting -- lands before // `onStarted` and is answered as an ordinary JSON error with its own status. After it, @@ -537,8 +522,6 @@ export function createHttpApp(deps: HttpGatewayDeps): OpenAPIHono & HttpApp } end(); }); - // The command keeps running after a client disconnects; what ends here is this - // route's interest in its output, terminally. return () => relay.drop(); }, }); @@ -546,10 +529,6 @@ export function createHttpApp(deps: HttpGatewayDeps): OpenAPIHono & HttpApp app.openapi({ ...componentInstallRoute, middleware: [agentAuth] }, async (c) => { const { workers, ...component } = c.req.valid("json"); - // Progress that arrives before the stream opens is held in order and flushed when it - // does. After the client is gone, a write is a no-op (`pipeSse`); the install itself - // carries on, and a repeat of this request joins it (ADR 0010 §6). Through a gateway each - // update names the worker it came from (§7). type ProgressEvent = ComponentProgress & { readonly workerId?: string }; const early: ProgressEvent[] = []; let deliver: ((progress: ProgressEvent) => void) | undefined; @@ -566,8 +545,6 @@ export function createHttpApp(deps: HttpGatewayDeps): OpenAPIHono & HttpApp }, }); - // `workers` names the gateway's relay: it asks each worker and answers with one result per - // worker. Without it, the install runs on the daemon this request reached. const dispatched: Promise = workers === undefined ? deps.dispatch("component.install", component, session) @@ -577,15 +554,6 @@ export function createHttpApp(deps: HttpGatewayDeps): OpenAPIHono & HttpApp (error: unknown) => ({ error, kind: "failed" }) as const, ); - // The same decision point as the exec route: every refusal that comes before an install - // (the token's role, the input, `downloads.policy`, a platform with no driver) is an - // ordinary JSON error with its own status. Once the installer has taken the call, the - // response is committed to a stream, which is what gives a call waiting behind another - // download its `200` and its keepalives at once. Bounded by the install's own budget, - // `downloads.timeoutMs`, which ends the call with `DOWNLOAD_TIMEOUT`. Through a gateway the - // decision point is the moment the targets are resolved: an unknown or unreachable worker - // named in `workers` is still a JSON error, and each worker's call is bounded by its own - // budget plus the gateway's backstop. const outcome = await Promise.race([settled, admitted.then(() => undefined)]); if (outcome?.kind === "failed") return errorResponse(c, outcome.error); @@ -645,7 +613,6 @@ export function createHttpApp(deps: HttpGatewayDeps): OpenAPIHono & HttpApp await deps.dispatch("lease.release", { leaseId: id }, session); - // A gateway holds no device state, so its answer is always the `reclaiming` default. const device = lease === undefined ? undefined : findDevice(deps, lease); return c.json( { @@ -660,9 +627,6 @@ export function createHttpApp(deps: HttpGatewayDeps): OpenAPIHono & HttpApp c.json(await deps.dispatch("lease.list", {}, buildHttpSession(c.get("identity"))), 200), ); - // The token records, for a console to name a lease's holder by its token's label. `token.list` - // is an admin operation, so an agent token gets `FORBIDDEN`/403 from the shared dispatcher, and - // its output schema has no secret and no hash, so neither can reach the body. app.openapi({ ...tokenListRoute, middleware: [agentAuth] }, async (c) => c.json(await deps.dispatch("token.list", {}, buildHttpSession(c.get("identity"))), 200), ); @@ -680,12 +644,6 @@ export function createHttpApp(deps: HttpGatewayDeps): OpenAPIHono & HttpApp return c.json(devicesReplySchema.parse({ devices }), 200); }); - // ADR 0005 §23's worker routes, registered in both modes (ADR 0012 §3). A worker answers them - // as a fleet of one: `GET /v1/workers` lists this host, and the drain, undrain and remove - // routes answer `501 UNSUPPORTED_IN_WORKER_MODE` from its dispatcher. - // - // Operator-role in effect: `worker.*` are admin operations, so an agent token gets - // `FORBIDDEN`/403 from the shared dispatcher rather than from a second check here. app.openapi({ ...workerListRoute, middleware: [agentAuth] }, async (c) => c.json(await deps.dispatch("worker.list", {}, buildHttpSession(c.get("identity"))), 200), ); @@ -792,7 +750,7 @@ export function createHttpApp(deps: HttpGatewayDeps): OpenAPIHono & HttpApp return "http-sse"; }, }); - // Role check + startup-readiness parking, same as every other dispatched operation; the + // why: Role check + startup-readiness parking, same as every other dispatched operation; the // actual live feed is wired below via `subscribe()`'s own return, since HTTP has no // persistent connection for the dispatcher's push mechanism to write through (ADR §8: "the // HTTP notice buffer stays, because a polling client has no connection to push to" -- @@ -842,7 +800,7 @@ export function createHttpApp(deps: HttpGatewayDeps): OpenAPIHono & HttpApp }); } - // `notices` holds a subscription for the app's lifetime -- exposed here rather than left to + // why: `notices` holds a subscription for the app's lifetime -- exposed here rather than left to // leak, so a caller composing this app into a longer-lived process (the daemon) can // unsubscribe it on shutdown. return Object.assign(app, { @@ -873,7 +831,7 @@ async function findOwnedLease( return lease; } -/** Best-effort lease lookup for a lease id, scoped to what the session's `lease.list` would +/** why: Best-effort lease lookup for a lease id, scoped to what the session's `lease.list` would * show it (own leases; admin sees all) -- used only to decorate a response after an * authoritative dispatch has already decided whether the request is allowed. Never used to * gate access itself (see the `DELETE /v1/leases/:id` route). */ @@ -894,7 +852,6 @@ function serializeRequest( case "queued": return { ...base, queuePosition: view.state.queuePosition, state: "queued" }; case "downloading": { - // `component`, `waiting` and `percent` when there is one, as the tracker built them. const { stage: _stage, ...download } = view.state; return { ...base, ...download, state: "downloading" }; } @@ -911,7 +868,7 @@ function serializeRequest( } } -/** The device a lease names. On a gateway both carry the `workerId` they came from, and a +/** why: The device a lease names. On a gateway both carry the `workerId` they came from, and a * device matches only on the lease's own worker: a device id is that worker's claim, so another * worker reporting the same id never answers for it. On a worker neither carries one. */ function findDevice( @@ -934,7 +891,7 @@ async function emptyBodyAsNone(c: Context, next: () => Promise): Promise