ankka-console 0.10.0 → 0.12.0

package/dist/client/control-plane.d.ts

@@ -1,4 +1,4 @@
-import { type AuthDiscovery, type CreateDeployToken, type CreateOrganization, type DeployTokenCreated, type DeployTokenSummary, type HistoryEntry, type LogsResponse, type MembersResponse, type OrganizationSummary, type ProjectDetail, type ProjectSummary, type Quota, type Role, type ServiceStatus, type SetRegistry, type Whoami } from "./schemas.ts";
+import { type AuthDiscovery, type BrokerDeclarationRequest, type ByteRatesRequest, type CreateDeployToken, type CreateOrganization, type DeployTokenCreated, type DeployTokenSummary, type GrantDetail, type GrantRequest, type HistoryEntry, type LogsResponse, type MachineRegistered, type MachineSummary, type MembersResponse, type OrganizationSummary, type ProjectBroker, type ProjectStatus, type CredentialReissued, type DatabaseSetting, type InstallationStatus, type ProjectHistoryView, type RestoreHoldStatus, type RehearsalView, type RestoreView, type ProjectDetail, type ProjectSecretSummary, type ProjectSummary, type ProjectTopic, type Quota, type ReceivedGrantDetail, type Role, type RolledBack, type ServiceStatus, type ServiceTopology, type SetRegistry, type TopicDeclarationRequest, type Whoami, type Installation } from "./schemas.ts";
 /** `fetch`'s shape; the server supplies one that presents the console's certificate. */
 export type Transport = (url: string, init: RequestInit) => Promise<Response>;
 /**
@@ -8,9 +8,13 @@ export type Transport = (url: string, init: RequestInit) => Promise<Response>;
 export type BearerSource = (options: {
     refresh: boolean;
 }) => Promise<string | null>;
+/** What a grantee's organization may do to a grant offered to it, as the route's last segment says it. */
+export type GrantAnswer = "accept" | "decline" | "relinquish";
 export interface LogsQuery {
     instance?: string;
     previous?: boolean;
+    /** The platform's container (the sidecar, or a web-hosted service's proxy) instead of the developer's. */
+    platform?: boolean;
     tail?: number;
     since?: number;
 }
@@ -31,6 +35,8 @@ export declare class ControlPlaneClient {
     constructor(options: ControlPlaneClientOptions);
     authDiscovery(): Promise<AuthDiscovery>;
     whoami(): Promise<Whoami>;
+    /** Its version, and its cloud when it names a provider; the key's name for an owner alone (feature 044). */
+    installation(): Promise<Installation>;
     listOrganizations(): Promise<OrganizationSummary[]>;
     getOrganization(id: string): Promise<OrganizationSummary>;
     createOrganization(id: string, body: CreateOrganization): Promise<void>;
@@ -49,6 +55,19 @@ export declare class ControlPlaneClient {
     tokens(id: string): Promise<DeployTokenSummary[]>;
     createToken(id: string, body: CreateDeployToken): Promise<DeployTokenCreated>;
     revokeToken(id: string, tokenId: string): Promise<void>;
+    /** The organization's registered machines; never a secret. */
+    machines(id: string): Promise<MachineSummary[]>;
+    /** Registers a machine. The reply carries its client secret, the only time it is ever shown. */
+    registerMachine(id: string, name: string): Promise<MachineRegistered>;
+    deleteMachine(id: string, name: string): Promise<void>;
+    setMachineByteRates(id: string, name: string, rates: ByteRatesRequest): Promise<MachineSummary>;
+    /** What the organization's machines and its projects' services hold, or are offered, from other projects. */
+    organizationGrants(id: string): Promise<ReceivedGrantDetail[]>;
+    /**
+     * Answers a grant from the grantee's side, as an owner of its organization: accepts or declines a
+     * pending one, or relinquishes an accepted one.
+     */
+    answerGrant(id: string, grantId: string, verb: GrantAnswer): Promise<void>;
     listProjects(): Promise<ProjectSummary[]>;
     getProject(id: string): Promise<ProjectDetail>;
     createProject(id: string, name: string, organizationId: string): Promise<void>;
@@ -56,12 +75,79 @@ export declare class ControlPlaneClient {
     deleteProject(id: string): Promise<void>;
     setRegistry(id: string, body: SetRegistry): Promise<void>;
     clearRegistry(id: string): Promise<void>;
+    /** Where the project's new buckets in Google Cloud Storage are made; moves no bucket. */
+    setProjectLocation(id: string, location: string): Promise<void>;
+    /** The installation's default location for the project's new buckets again. */
+    clearProjectLocation(id: string): Promise<void>;
+    /** Entries of a project secret, merged into what it holds. The values are never read back. */
+    setProjectSecret(id: string, name: string, entries: Record<string, string>): Promise<void>;
+    unsetProjectSecretEntry(id: string, name: string, entry: string): Promise<void>;
+    listProjectSecrets(id: string): Promise<ProjectSecretSummary[]>;
+    /** Declares a topic on the project, or raises its partitions; its compaction and contract with it. */
+    declareTopic(id: string, name: string, request: TopicDeclarationRequest): Promise<void>;
+    /** The schema document a topic's contract was declared with. */
+    topicSchema(id: string, name: string): Promise<unknown>;
+    /** Stops declaring a topic; it stays on the broker. */
+    removeTopic(id: string, name: string): Promise<void>;
+    listTopics(id: string): Promise<ProjectTopic[]>;
+    /** Declares a broker beside the installation's, or changes where it is; the project secret holds its credential. */
+    declareBroker(id: string, name: string, request: BrokerDeclarationRequest): Promise<void>;
+    /** Stops declaring a broker; a service naming it is refused at its next start. */
+    removeBroker(id: string, name: string): Promise<void>;
+    listBrokers(id: string): Promise<ProjectBroker[]>;
+    /** Whether the project is backed up, how far back it can be restored, its database and its restores. */
+    projectStatus(id: string): Promise<ProjectStatus>;
+    /** Restores the project's database to a moment, into a new cluster beside the current one. Owners only. */
+    restoreProject(id: string, moment: string, line?: string): Promise<RestoreView>;
+    /** Issues the project's backup credential again; the old key stops working. Owners only. */
+    reissueBackupCredential(id: string): Promise<CredentialReissued>;
+    listRestores(id: string): Promise<RestoreView[]>;
+    /** Who did what to the project's database, newest first. */
+    projectHistory(id: string): Promise<ProjectHistoryView[]>;
+    projectDatabase(id: string): Promise<DatabaseSetting>;
+    /** Sets what the project asks of its database, whole: replicas, synchronous writes, retention, rehearsals. */
+    setProjectDatabase(id: string, setting: DatabaseSetting): Promise<DatabaseSetting>;
+    /** Where the installation's backups go, for how long, and how safely: `backups` on `GET /installation`. */
+    backups(): Promise<InstallationStatus>;
+    /** Whether the control plane is held after its own database was restored, and what differs. */
+    restoreHold(): Promise<RestoreHoldStatus>;
+    /** Releases a held control plane; a platform administrator's alone. */
+    releaseRestoreHold(): Promise<RestoreHoldStatus>;
+    getRestore(id: string, name: string): Promise<RestoreView>;
+    /** Rehearses a restore in a namespace of its own; it changes nothing of the project. */
+    rehearseProject(id: string, moment?: string): Promise<RehearsalView>;
+    listRehearsals(id: string): Promise<RehearsalView[]>;
+    /** Moves one service to another of its project's database clusters: a restore, or back. */
+    switchService(projectId: string, name: string, cluster: string): Promise<ServiceStatus>;
+    /** Grants a service of another project, or a machine, one route, method, topic or the erasure. */
+    makeGrant(id: string, request: GrantRequest): Promise<GrantDetail>;
+    /** The project's grants, live and ended, each with whether it is in effect and why not. */
+    grants(id: string): Promise<GrantDetail[]>;
+    /** What other projects granted this project's services, and every change to each. */
+    receivedGrants(id: string): Promise<ReceivedGrantDetail[]>;
+    /** Ends a grant from the grantor's side: a pending one is withdrawn, an accepted one revoked. */
+    endGrant(id: string, grantId: string): Promise<void>;
     listServices(projectId: string): Promise<ServiceStatus[]>;
     getService(projectId: string, name: string): Promise<ServiceStatus>;
     /** The descriptor is sent as the text the person gave; the control plane is the one that validates it. */
     applyService(projectId: string, name: string, descriptor: string): Promise<ServiceStatus>;
     serviceOperation(projectId: string, name: string, operation: "pause" | "resume" | "restart" | "expose" | "unexpose"): Promise<void>;
+    /** Add a custom hostname; a refusal is the control plane's, shown as it says it. */
+    addHostname(projectId: string, name: string, hostname: string): Promise<ServiceStatus>;
+    removeHostname(projectId: string, name: string, hostname: string): Promise<ServiceStatus>;
+    /** Issues the service's storage credential again; the old one works for the rotation grace. */
+    reissueStorageCredential(projectId: string, name: string): Promise<ServiceStatus>;
+    /** Applies the installation's current bucket settings to the service's bucket in Google Cloud Storage. */
+    reapplyStorageSettings(projectId: string, name: string): Promise<ServiceStatus>;
+    /** Moves the service's bucket from Garage to Google Cloud Storage; an omitted bound is the control plane's default. */
+    moveStorage(projectId: string, name: string, writePauseBound?: string): Promise<ServiceStatus>;
     deleteService(projectId: string, name: string): Promise<void>;
+    /** Roll a service back to a generation: its descriptor applied again, as a new generation. */
+    rollback(projectId: string, name: string, generation: number): Promise<RolledBack>;
+    /** The descriptor applied at a generation, as the control plane accepts one. */
+    descriptor(projectId: string, name: string, generation: number): Promise<unknown>;
     history(projectId: string, name: string): Promise<HistoryEntry[]>;
     logs(projectId: string, name: string, query?: LogsQuery): Promise<LogsResponse>;
+    /** Every instance's topology, merged by the control plane; 404 when no instance runs. */
+    topology(projectId: string, name: string): Promise<ServiceTopology>;
 }

package/dist/client/control-plane.js

@@ -1,5 +1,7 @@
 import { ControlPlaneError, ControlPlaneUnreachable, SignInRequired } from "./errors.js";
-import { authDiscoverySchema, deployTokenCreatedSchema, deployTokenSummarySchema, historyEntrySchema, logsResponseSchema, membersResponseSchema, organizationSummarySchema, projectDetailSchema, projectSummarySchema, serviceStatusSchema, whoamiSchema, } from "./schemas.js";
+import { authDiscoverySchema, deployTokenCreatedSchema, deployTokenSummarySchema, grantDetailSchema, historyEntrySchema, machineRegisteredSchema, machineSummarySchema, logsResponseSchema, membersResponseSchema, organizationSummarySchema, projectBrokerSchema, projectStatusSchema, credentialReissuedSchema, databaseSettingSchema, projectHistoryViewSchema, restoreHoldStatusSchema, rehearsalViewSchema, restoreViewSchema, projectDetailSchema, projectSecretSummarySchema, projectSummarySchema, projectTopicSchema, receivedGrantDetailSchema, rolledBackSchema, serviceStatusSchema, serviceTopologySchema, whoamiSchema, installationSchema, } from "./schemas.js";
+/** A descriptor is passed through as the control plane wrote it, as `applyService` takes one. */
+const anyJson = { parse: (value) => value };
 const arrayOf = (schema) => ({
     parse: (value) => {
         if (!Array.isArray(value))
@@ -31,6 +33,11 @@ export class ControlPlaneClient {
     whoami() {
         return this.#call("GET", "/auth/whoami", { schema: whoamiSchema });
     }
+    // ── The installation ──────────────────────────────────────────────────────
+    /** Its version, and its cloud when it names a provider; the key's name for an owner alone (feature 044). */
+    installation() {
+        return this.#call("GET", "/installation", { schema: installationSchema });
+    }
     // ── Organizations ─────────────────────────────────────────────────────────
     listOrganizations() {
         return this.#call("GET", "/organizations", { schema: arrayOf(organizationSummarySchema) });
@@ -97,6 +104,35 @@ export class ControlPlaneClient {
     revokeToken(id, tokenId) {
         return this.#call("DELETE", `/organizations/${segment(id)}/tokens/${segment(tokenId)}`);
     }
+    // ── Machines and the grants an organization holds (feature 040) ─────────
+    /** The organization's registered machines; never a secret. */
+    machines(id) {
+        return this.#call("GET", `/organizations/${segment(id)}/machines`, { schema: arrayOf(machineSummarySchema) });
+    }
+    /** Registers a machine. The reply carries its client secret, the only time it is ever shown. */
+    registerMachine(id, name) {
+        return this.#call("POST", `/organizations/${segment(id)}/machines`, { body: { name }, schema: machineRegisteredSchema });
+    }
+    deleteMachine(id, name) {
+        return this.#call("DELETE", `/organizations/${segment(id)}/machines/${segment(name)}`);
+    }
+    setMachineByteRates(id, name, rates) {
+        return this.#call("PUT", `/organizations/${segment(id)}/machines/${segment(name)}/byte-rates`, {
+            body: rates,
+            schema: machineSummarySchema,
+        });
+    }
+    /** What the organization's machines and its projects' services hold, or are offered, from other projects. */
+    organizationGrants(id) {
+        return this.#call("GET", `/organizations/${segment(id)}/grants`, { schema: arrayOf(receivedGrantDetailSchema) });
+    }
+    /**
+     * Answers a grant from the grantee's side, as an owner of its organization: accepts or declines a
+     * pending one, or relinquishes an accepted one.
+     */
+    answerGrant(id, grantId, verb) {
+        return this.#call("POST", `/organizations/${segment(id)}/grants/${segment(grantId)}/${verb}`);
+    }
     // ── Projects ──────────────────────────────────────────────────────────────
     listProjects() {
         return this.#call("GET", "/projects", { schema: arrayOf(projectSummarySchema) });
@@ -119,6 +155,123 @@ export class ControlPlaneClient {
     clearRegistry(id) {
         return this.#call("DELETE", `/projects/${segment(id)}/registry`);
     }
+    /** Where the project's new buckets in Google Cloud Storage are made; moves no bucket. */
+    setProjectLocation(id, location) {
+        return this.#call("PUT", `/projects/${segment(id)}/location`, { body: { location } });
+    }
+    /** The installation's default location for the project's new buckets again. */
+    clearProjectLocation(id) {
+        return this.#call("DELETE", `/projects/${segment(id)}/location`);
+    }
+    /** Entries of a project secret, merged into what it holds. The values are never read back. */
+    setProjectSecret(id, name, entries) {
+        return this.#call("PUT", `/projects/${segment(id)}/secrets/${segment(name)}`, { body: { entries } });
+    }
+    unsetProjectSecretEntry(id, name, entry) {
+        return this.#call("DELETE", `/projects/${segment(id)}/secrets/${segment(name)}?entry=${segment(entry)}`);
+    }
+    listProjectSecrets(id) {
+        return this.#call("GET", `/projects/${segment(id)}/secrets`, { schema: arrayOf(projectSecretSummarySchema) });
+    }
+    /** Declares a topic on the project, or raises its partitions; its compaction and contract with it. */
+    declareTopic(id, name, request) {
+        return this.#call("PUT", `/projects/${segment(id)}/topics/${segment(name)}`, { body: request });
+    }
+    /** The schema document a topic's contract was declared with. */
+    topicSchema(id, name) {
+        return this.#call("GET", `/projects/${segment(id)}/topics/${segment(name)}/schema`, { schema: { parse: (v) => v } });
+    }
+    /** Stops declaring a topic; it stays on the broker. */
+    removeTopic(id, name) {
+        return this.#call("DELETE", `/projects/${segment(id)}/topics/${segment(name)}`);
+    }
+    listTopics(id) {
+        return this.#call("GET", `/projects/${segment(id)}/topics`, { schema: arrayOf(projectTopicSchema) });
+    }
+    /** Declares a broker beside the installation's, or changes where it is; the project secret holds its credential. */
+    declareBroker(id, name, request) {
+        return this.#call("PUT", `/projects/${segment(id)}/brokers/${segment(name)}`, { body: request });
+    }
+    /** Stops declaring a broker; a service naming it is refused at its next start. */
+    removeBroker(id, name) {
+        return this.#call("DELETE", `/projects/${segment(id)}/brokers/${segment(name)}`);
+    }
+    listBrokers(id) {
+        return this.#call("GET", `/projects/${segment(id)}/brokers`, { schema: arrayOf(projectBrokerSchema) });
+    }
+    // ── Backups and recovery ──────────────────────────────────────────────────
+    /** Whether the project is backed up, how far back it can be restored, its database and its restores. */
+    projectStatus(id) {
+        return this.#call("GET", `/projects/${segment(id)}/status`, { schema: projectStatusSchema });
+    }
+    /** Restores the project's database to a moment, into a new cluster beside the current one. Owners only. */
+    restoreProject(id, moment, line) {
+        return this.#call("POST", `/projects/${segment(id)}/restores`, { body: { moment, line }, schema: restoreViewSchema });
+    }
+    /** Issues the project's backup credential again; the old key stops working. Owners only. */
+    reissueBackupCredential(id) {
+        return this.#call("POST", `/projects/${segment(id)}/backups/credential`, { schema: credentialReissuedSchema });
+    }
+    listRestores(id) {
+        return this.#call("GET", `/projects/${segment(id)}/restores`, { schema: arrayOf(restoreViewSchema) });
+    }
+    /** Who did what to the project's database, newest first. */
+    projectHistory(id) {
+        return this.#call("GET", `/projects/${segment(id)}/history`, { schema: arrayOf(projectHistoryViewSchema) });
+    }
+    projectDatabase(id) {
+        return this.#call("GET", `/projects/${segment(id)}/database`, { schema: databaseSettingSchema });
+    }
+    /** Sets what the project asks of its database, whole: replicas, synchronous writes, retention, rehearsals. */
+    setProjectDatabase(id, setting) {
+        return this.#call("PUT", `/projects/${segment(id)}/database`, { body: setting, schema: databaseSettingSchema });
+    }
+    /** Where the installation's backups go, for how long, and how safely: `backups` on `GET /installation`. */
+    async backups() {
+        const installation = await this.installation();
+        if (!installation.backups)
+            throw new Error("the control plane reported nothing of its backups");
+        return installation.backups;
+    }
+    /** Whether the control plane is held after its own database was restored, and what differs. */
+    restoreHold() {
+        return this.#call("GET", "/installation/restore", { schema: restoreHoldStatusSchema });
+    }
+    /** Releases a held control plane; a platform administrator's alone. */
+    releaseRestoreHold() {
+        return this.#call("POST", "/installation/restore/release", { schema: restoreHoldStatusSchema });
+    }
+    getRestore(id, name) {
+        return this.#call("GET", `/projects/${segment(id)}/restores/${segment(name)}`, { schema: restoreViewSchema });
+    }
+    /** Rehearses a restore in a namespace of its own; it changes nothing of the project. */
+    rehearseProject(id, moment) {
+        return this.#call("POST", `/projects/${segment(id)}/rehearsals`, { body: moment ? { moment } : {}, schema: rehearsalViewSchema });
+    }
+    listRehearsals(id) {
+        return this.#call("GET", `/projects/${segment(id)}/rehearsals`, { schema: arrayOf(rehearsalViewSchema) });
+    }
+    /** Moves one service to another of its project's database clusters: a restore, or back. */
+    switchService(projectId, name, cluster) {
+        return this.#call("POST", `/services/${segment(projectId)}/${segment(name)}/switch`, { body: { cluster }, schema: serviceStatusSchema });
+    }
+    // ── Grants (feature 040) ──────────────────────────────────────────────────
+    /** Grants a service of another project, or a machine, one route, method, topic or the erasure. */
+    makeGrant(id, request) {
+        return this.#call("POST", `/projects/${segment(id)}/grants`, { body: request, schema: grantDetailSchema });
+    }
+    /** The project's grants, live and ended, each with whether it is in effect and why not. */
+    grants(id) {
+        return this.#call("GET", `/projects/${segment(id)}/grants`, { schema: arrayOf(grantDetailSchema) });
+    }
+    /** What other projects granted this project's services, and every change to each. */
+    receivedGrants(id) {
+        return this.#call("GET", `/projects/${segment(id)}/grants/received`, { schema: arrayOf(receivedGrantDetailSchema) });
+    }
+    /** Ends a grant from the grantor's side: a pending one is withdrawn, an accepted one revoked. */
+    endGrant(id, grantId) {
+        return this.#call("DELETE", `/projects/${segment(id)}/grants/${segment(grantId)}`);
+    }
     // ── Services ──────────────────────────────────────────────────────────────
     listServices(projectId) {
         return this.#call("GET", `/services/${segment(projectId)}`, { schema: arrayOf(serviceStatusSchema) });
@@ -136,9 +289,48 @@ export class ControlPlaneClient {
     serviceOperation(projectId, name, operation) {
         return this.#call("POST", `/services/${segment(projectId)}/${segment(name)}/${operation}`);
     }
+    /** Add a custom hostname; a refusal is the control plane's, shown as it says it. */
+    addHostname(projectId, name, hostname) {
+        return this.#call("PUT", `/services/${segment(projectId)}/${segment(name)}/hostnames/${segment(hostname)}`, {
+            schema: serviceStatusSchema,
+        });
+    }
+    removeHostname(projectId, name, hostname) {
+        return this.#call("DELETE", `/services/${segment(projectId)}/${segment(name)}/hostnames/${segment(hostname)}`, {
+            schema: serviceStatusSchema,
+        });
+    }
+    /** Issues the service's storage credential again; the old one works for the rotation grace. */
+    reissueStorageCredential(projectId, name) {
+        return this.#call("POST", `/services/${segment(projectId)}/${segment(name)}/storage-credential`, { schema: serviceStatusSchema });
+    }
+    /** Applies the installation's current bucket settings to the service's bucket in Google Cloud Storage. */
+    reapplyStorageSettings(projectId, name) {
+        return this.#call("POST", `/services/${segment(projectId)}/${segment(name)}/storage/settings`, { schema: serviceStatusSchema });
+    }
+    /** Moves the service's bucket from Garage to Google Cloud Storage; an omitted bound is the control plane's default. */
+    moveStorage(projectId, name, writePauseBound) {
+        return this.#call("POST", `/services/${segment(projectId)}/${segment(name)}/storage/move`, {
+            body: writePauseBound ? { writePauseBound } : {},
+            schema: serviceStatusSchema,
+        });
+    }
     deleteService(projectId, name) {
         return this.#call("DELETE", `/services/${segment(projectId)}/${segment(name)}`);
     }
+    /** Roll a service back to a generation: its descriptor applied again, as a new generation. */
+    rollback(projectId, name, generation) {
+        return this.#call("POST", `/services/${segment(projectId)}/${segment(name)}/rollback`, {
+            body: { generation },
+            schema: rolledBackSchema,
+        });
+    }
+    /** The descriptor applied at a generation, as the control plane accepts one. */
+    descriptor(projectId, name, generation) {
+        return this.#call("GET", `/services/${segment(projectId)}/${segment(name)}/descriptor?generation=${generation}`, {
+            schema: anyJson,
+        });
+    }
     history(projectId, name) {
         return this.#call("GET", `/services/${segment(projectId)}/${segment(name)}/history`, {
             schema: arrayOf(historyEntrySchema),
@@ -150,6 +342,8 @@ export class ControlPlaneClient {
             params.set("instance", query.instance);
         if (query.previous)
             params.set("previous", "true");
+        if (query.platform)
+            params.set("platform", "true");
         if (query.tail !== undefined)
             params.set("tail", String(query.tail));
         if (query.since !== undefined)
@@ -159,6 +353,12 @@ export class ControlPlaneClient {
             schema: logsResponseSchema,
         });
     }
+    /** Every instance's topology, merged by the control plane; 404 when no instance runs. */
+    topology(projectId, name) {
+        return this.#call("GET", `/services/${segment(projectId)}/${segment(name)}/topology`, {
+            schema: serviceTopologySchema,
+        });
+    }
     // ── Transport ─────────────────────────────────────────────────────────────
     async #call(method, path, options = {}) {
         const url = this.#baseUrl + path;