@astrale-os/sdk 0.6.0-beta.21 → 0.6.0-beta.23

package/dist/deployment/worker/request.d.ts

@@ -0,0 +1,118 @@
+import type { Digest } from '@astrale-os/kernel-protocol/artifact';
+import type { WorkerBuildManifest, WorkerCode, WorkerModule } from './build.js';
+import type { WorkerConfigurationV1 } from './configuration.js';
+import type { WorkerContentV1 } from './content.js';
+import type { WorkerRecord, WorkerRecordWireV1 } from './record.js';
+export declare const WORKER_DEPLOYMENT_REQUEST_FORMAT = "astrale.worker.deployment-request";
+export declare const WORKER_DEPLOYMENT_REQUEST_VERSION = 1;
+/**
+ * `WorkerDeploymentRequestV1`: one Worker release to host as a deployment of the Service of its
+ * project and environment. Its host knows nothing of what the Worker serves: it recomputes the
+ * build digest from the uploaded bytes and the label from the Service name, the build and the
+ * configuration, and refuses a request that states another (`build-mismatch`,
+ * `address-mismatch`), so a deployer that predicted an address is never served elsewhere. Its
+ * `secrets` are bound to a new deployment, or rewritten in place on the reused one, and never
+ * stored; a host never journals the request.
+ */
+export interface WorkerDeploymentRequestV1 {
+    readonly format: typeof WORKER_DEPLOYMENT_REQUEST_FORMAT;
+    readonly version: typeof WORKER_DEPLOYMENT_REQUEST_VERSION;
+    /**
+     * The Identity that owns the Service when this deploy creates it: the caller, or one it acts as.
+     * The caller when absent; an existing Service keeps its owner.
+     */
+    readonly owner?: string;
+    /** Any project name (`PROJECT_NAME`); a Domain deployer names its Domain's origin. */
+    readonly project: string;
+    readonly environment: string;
+    /** `<service>-<content>`, as `workerDeploymentAddress` derives it. */
+    readonly label: string;
+    /** The build digest of `worker`, as `workerBuildDigest` derives it. */
+    readonly buildDigest: string;
+    readonly configuration: WorkerConfigurationV1;
+    readonly worker: WorkerCodeWireV1;
+    /** Exactly when `configuration.record`: the record the deployment serves. */
+    readonly record?: WorkerRecordWireV1;
+    /**
+     * Local paths that must answer 200 with the deployment's `x-astrale-worker-version` before the
+     * deployment is activated; none when absent. A probe is not part of the configuration.
+     */
+    readonly readiness?: readonly string[];
+    /** The secret values, exactly the names `configuration.secrets` declares. */
+    readonly secrets: Readonly<Record<string, string>>;
+    /** Whether the Service serves the deployment once it is active; `true` when absent. */
+    readonly promote?: boolean;
+}
+/** The code of one Worker on the wire, each file in its content envelope. */
+export interface WorkerCodeWireV1 {
+    readonly manifest: WorkerBuildManifest;
+    readonly mainModule: string;
+    readonly modules: readonly {
+        readonly name: string;
+        readonly kind: WorkerModule['kind'];
+        readonly content: WorkerContentV1;
+    }[];
+    readonly assets?: readonly {
+        readonly path: string;
+        readonly contentType?: string;
+        readonly content: WorkerContentV1;
+    }[];
+}
+/** One Worker deployment as its deployer describes it, before its address is derived. */
+export interface WorkerDeploymentInput {
+    readonly owner?: string;
+    readonly project: string;
+    readonly environment: string;
+    readonly worker: WorkerCode;
+    readonly configuration: WorkerConfigurationV1;
+    readonly record?: WorkerRecord;
+    readonly readiness?: readonly string[];
+    readonly secrets?: Readonly<Record<string, string>>;
+    readonly promote?: boolean;
+}
+/** Where one Worker deployment is addressed: its Service, its digests and its label. */
+export interface WorkerDeploymentAddress {
+    readonly service: string;
+    readonly buildDigest: Digest;
+    readonly configurationDigest: Digest;
+    readonly label: string;
+}
+/** One Worker deployment as a host admitted it: decoded, digested and addressed. */
+export interface WorkerDeployment extends WorkerDeploymentAddress {
+    readonly owner?: string;
+    readonly project: string;
+    readonly environment: string;
+    readonly worker: WorkerCode;
+    readonly configuration: WorkerConfigurationV1;
+    readonly record?: WorkerRecord;
+    readonly readiness: readonly string[];
+    readonly secrets: Readonly<Record<string, string>>;
+    readonly promote: boolean;
+}
+/** Why a host refuses a Worker deployment request before reading or writing anything. */
+export declare class WorkerDeploymentRefusal extends Error {
+    readonly reason: 'invalid-deployment' | 'build-mismatch' | 'address-mismatch';
+    readonly name = "WorkerDeploymentRefusal";
+    constructor(reason: 'invalid-deployment' | 'build-mismatch' | 'address-mismatch', message: string, options?: ErrorOptions);
+}
+/** The address one Worker deployment gets: its Service's name, its two digests and its label. */
+export declare function workerDeploymentAddress(input: {
+    readonly project: string;
+    readonly environment: string;
+    readonly worker: WorkerCode;
+    readonly configuration: WorkerConfigurationV1;
+}): WorkerDeploymentAddress;
+/**
+ * Encode one Worker deployment as its request: its address derived, every file in its content
+ * envelope. A deployment its host would refuse as invalid is refused here, before any call.
+ */
+export declare function encodeWorkerDeploymentRequest(input: WorkerDeploymentInput): Promise<WorkerDeploymentRequestV1>;
+/**
+ * Decode and admit one Worker deployment request, as a host does before any graph or provider
+ * effect: exactly this request shape, every file decoded within its bounds and the Worker's, the
+ * configuration canonical, the record exactly when the configuration asks for one, the secrets
+ * exactly the names it declares. Then the build digest is recomputed from the decoded bytes
+ * (`build-mismatch` when the request states another) and the label from the Service name, that
+ * digest and the configuration (`address-mismatch`). Every refusal is a `WorkerDeploymentRefusal`.
+ */
+export declare function decodeWorkerDeploymentRequest(input: unknown): Promise<WorkerDeployment>;

package/dist/deployment/worker/request.js

@@ -0,0 +1,280 @@
+import { serviceName, workerDeploymentLabel } from './address.js';
+import { acceptWorkerCode, workerBuildDigest } from './build.js';
+import { acceptWorkerConfiguration, workerConfigurationDigest } from './configuration.js';
+import { decodeWorkerContent, encodeWorkerContent } from './content.js';
+import { WORKER_DEPLOYMENT_LIMITS } from './limits.js';
+import { acceptWorkerRecord, decodeWorkerRecord, encodeWorkerRecord } from './record.js';
+export const WORKER_DEPLOYMENT_REQUEST_FORMAT = 'astrale.worker.deployment-request';
+export const WORKER_DEPLOYMENT_REQUEST_VERSION = 1;
+/** Why a host refuses a Worker deployment request before reading or writing anything. */
+export class WorkerDeploymentRefusal extends Error {
+    reason;
+    name = 'WorkerDeploymentRefusal';
+    constructor(reason, message, options) {
+        super(message, options);
+        this.reason = reason;
+    }
+}
+/** The address one Worker deployment gets: its Service's name, its two digests and its label. */
+export function workerDeploymentAddress(input) {
+    const service = serviceName(input.project, input.environment);
+    const buildDigest = workerBuildDigest(input.worker);
+    const configurationDigest = workerConfigurationDigest(input.configuration);
+    return Object.freeze({
+        service,
+        buildDigest,
+        configurationDigest,
+        label: workerDeploymentLabel({ service, buildDigest, configurationDigest }),
+    });
+}
+/**
+ * Encode one Worker deployment as its request: its address derived, every file in its content
+ * envelope. A deployment its host would refuse as invalid is refused here, before any call.
+ */
+export async function encodeWorkerDeploymentRequest(input) {
+    const deployment = admitDeployment(input);
+    const { worker } = deployment;
+    const modules = await Promise.all(worker.modules.map(async (module) => Object.freeze({
+        name: module.name,
+        kind: module.kind,
+        content: await encodeWorkerContent(module.bytes),
+    })));
+    const assets = await Promise.all((worker.assets ?? []).map(async (asset) => Object.freeze({
+        path: asset.path,
+        ...(asset.contentType === undefined ? {} : { contentType: asset.contentType }),
+        content: await encodeWorkerContent(asset.bytes),
+    })));
+    return Object.freeze({
+        format: WORKER_DEPLOYMENT_REQUEST_FORMAT,
+        version: WORKER_DEPLOYMENT_REQUEST_VERSION,
+        ...(deployment.owner === undefined ? {} : { owner: deployment.owner }),
+        project: deployment.project,
+        environment: deployment.environment,
+        label: deployment.label,
+        buildDigest: deployment.buildDigest,
+        configuration: deployment.configuration,
+        worker: Object.freeze({
+            manifest: worker.manifest,
+            mainModule: worker.mainModule,
+            modules: Object.freeze(modules),
+            ...(assets.length === 0 ? {} : { assets: Object.freeze(assets) }),
+        }),
+        ...(deployment.record === undefined ? {} : { record: encodeWorkerRecord(deployment.record) }),
+        ...(deployment.readiness.length === 0 ? {} : { readiness: deployment.readiness }),
+        secrets: deployment.secrets,
+        ...(input.promote === undefined ? {} : { promote: input.promote }),
+    });
+}
+/**
+ * Decode and admit one Worker deployment request, as a host does before any graph or provider
+ * effect: exactly this request shape, every file decoded within its bounds and the Worker's, the
+ * configuration canonical, the record exactly when the configuration asks for one, the secrets
+ * exactly the names it declares. Then the build digest is recomputed from the decoded bytes
+ * (`build-mismatch` when the request states another) and the label from the Service name, that
+ * digest and the configuration (`address-mismatch`). Every refusal is a `WorkerDeploymentRefusal`.
+ */
+export async function decodeWorkerDeploymentRequest(input) {
+    let deployment;
+    let stated;
+    try {
+        const value = exact(input, [
+            'format',
+            'version',
+            'project',
+            'environment',
+            'label',
+            'buildDigest',
+            'configuration',
+            'worker',
+            'secrets',
+        ], ['owner', 'record', 'readiness', 'promote'], 'request');
+        if (value.format !== WORKER_DEPLOYMENT_REQUEST_FORMAT ||
+            value.version !== WORKER_DEPLOYMENT_REQUEST_VERSION) {
+            throw new TypeError('The request is not a WorkerDeploymentRequestV1.');
+        }
+        stated = { buildDigest: value.buildDigest, label: value.label };
+        deployment = admitDeployment({
+            ...(value.owner === undefined ? {} : { owner: value.owner }),
+            project: value.project,
+            environment: value.environment,
+            worker: await decodeCode(value.worker),
+            configuration: value.configuration,
+            ...(value.record === undefined ? {} : { record: decodeWorkerRecord(value.record) }),
+            ...(value.readiness === undefined ? {} : { readiness: value.readiness }),
+            secrets: value.secrets,
+            ...(value.promote === undefined ? {} : { promote: value.promote }),
+        });
+    }
+    catch (cause) {
+        if (!(cause instanceof TypeError))
+            throw cause;
+        throw new WorkerDeploymentRefusal('invalid-deployment', cause.message, { cause });
+    }
+    if (stated.buildDigest !== deployment.buildDigest) {
+        throw new WorkerDeploymentRefusal('build-mismatch', `The uploaded Worker has build digest ${deployment.buildDigest}, not ${quoted(stated.buildDigest)}.`);
+    }
+    if (stated.label !== deployment.label) {
+        throw new WorkerDeploymentRefusal('address-mismatch', `This release of this Service is deployed at ${deployment.label}, not ${quoted(stated.label)}.`);
+    }
+    return deployment;
+}
+/** A stated value as a refusal names it: short printable text as written, anything else not. */
+function quoted(value) {
+    return typeof value === 'string' && value.length <= 80 && !/[\p{Cc}]/u.test(value)
+        ? value
+        : 'the one stated';
+}
+/** Admit the decoded parts of one deployment and derive its address. */
+function admitDeployment(input) {
+    if (input === null || typeof input !== 'object')
+        invalid('it is not an object');
+    const configuration = acceptWorkerConfiguration(input.configuration);
+    const worker = acceptWorkerCode(input.worker);
+    const secrets = acceptSecrets(input.secrets ?? {}, configuration.secrets);
+    if ((input.record !== undefined) !== configuration.record) {
+        invalid(configuration.record
+            ? 'its configuration serves a record it does not carry'
+            : 'it carries a record its configuration does not serve');
+    }
+    const record = input.record === undefined ? undefined : acceptWorkerRecord(input.record);
+    const readiness = acceptReadiness(input.readiness ?? []);
+    if (input.owner !== undefined && !isText(input.owner, 256))
+        invalid('its owner is invalid');
+    if (input.promote !== undefined && typeof input.promote !== 'boolean') {
+        invalid('its promote option is not a boolean');
+    }
+    const address = workerDeploymentAddress({
+        project: input.project,
+        environment: input.environment,
+        worker,
+        configuration,
+    });
+    return Object.freeze({
+        ...address,
+        ...(input.owner === undefined ? {} : { owner: input.owner }),
+        project: input.project,
+        environment: input.environment,
+        worker,
+        configuration,
+        ...(record === undefined ? {} : { record }),
+        readiness,
+        secrets,
+        promote: input.promote ?? true,
+    });
+}
+/** Exactly the declared secret names, each value bounded text. */
+function acceptSecrets(input, declared) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        invalid('its secrets are not an object');
+    }
+    const names = Reflect.ownKeys(input);
+    if (names.length !== declared.length ||
+        names.some((name) => typeof name !== 'string' || !declared.includes(name))) {
+        invalid('its secrets are not exactly the names its configuration declares');
+    }
+    for (const name of declared) {
+        if (typeof input[name] !== 'string' ||
+            input[name].length > WORKER_DEPLOYMENT_LIMITS.valueLength) {
+            invalid(`secret ${name} is not text within its size limit`);
+        }
+    }
+    return Object.freeze(Object.fromEntries(declared.map((name) => [name, input[name]])));
+}
+/**
+ * Readiness paths: at most `readinessPaths` distinct canonical local paths, never a host, a query,
+ * credentials or a redirect destination.
+ */
+function acceptReadiness(input) {
+    if (!Array.isArray(input) ||
+        input.length > WORKER_DEPLOYMENT_LIMITS.readinessPaths ||
+        new Set(input).size !== input.length) {
+        invalid('its readiness paths are invalid');
+    }
+    for (const path of input) {
+        if (typeof path !== 'string' ||
+            path.length > 1_024 ||
+            !/^\/(?:[A-Za-z0-9._~-]+\/)*[A-Za-z0-9._~-]*$/u.test(path) ||
+            path.split('/').some((part) => part === '.' || part === '..')) {
+            invalid('its readiness paths are not canonical local paths');
+        }
+    }
+    return Object.freeze([...input]);
+}
+/** Decode the code of one Worker, each file within its bounds and all within the Worker's. */
+async function decodeCode(input) {
+    const value = exact(input, ['manifest', 'mainModule', 'modules'], ['assets'], 'worker');
+    const limits = WORKER_DEPLOYMENT_LIMITS;
+    if (!Array.isArray(value.modules) || value.modules.length > limits.modules) {
+        invalid('its modules are invalid');
+    }
+    if (value.assets !== undefined &&
+        (!Array.isArray(value.assets) || value.assets.length > limits.assets)) {
+        invalid('its assets are invalid');
+    }
+    let remaining = limits.workerSize;
+    const decode = async (content, size, base64Size) => {
+        const bytes = await decodeWorkerContent(content, {
+            size: Math.min(size, remaining),
+            base64Size,
+        });
+        remaining -= bytes.byteLength;
+        return bytes;
+    };
+    const modules = [];
+    for (const entry of value.modules) {
+        const module = exact(entry, ['name', 'kind', 'content'], [], 'module');
+        modules.push({
+            name: module.name,
+            kind: module.kind,
+            bytes: await decode(module.content, limits.moduleSize, limits.moduleBase64Size),
+        });
+    }
+    const assets = [];
+    for (const entry of (value.assets ?? [])) {
+        const asset = exact(entry, ['path', 'content'], ['contentType'], 'asset');
+        if (asset.contentType !== undefined && !isText(asset.contentType, 256)) {
+            invalid('an asset content type is invalid');
+        }
+        assets.push({
+            path: asset.path,
+            bytes: await decode(asset.content, limits.assetSize, limits.assetBase64Size),
+            ...(asset.contentType === undefined ? {} : { contentType: asset.contentType }),
+        });
+    }
+    return {
+        manifest: value.manifest,
+        mainModule: value.mainModule,
+        modules,
+        ...(assets.length === 0 ? {} : { assets }),
+    };
+}
+function isText(value, maximum) {
+    return (typeof value === 'string' &&
+        value.length > 0 &&
+        value.length <= maximum &&
+        !/[\p{Cc}]/u.test(value));
+}
+function exact(input, required, optional, label) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        invalid(`its ${label} is not an object`);
+    }
+    for (const key of Reflect.ownKeys(input)) {
+        if (typeof key !== 'string' || (!required.includes(key) && !optional.includes(key))) {
+            invalid(`its ${label} has an unknown member ${String(key)}`);
+        }
+    }
+    const value = input;
+    for (const key of required) {
+        if (!Object.hasOwn(value, key))
+            invalid(`its ${label} has no ${key}`);
+    }
+    for (const key of optional) {
+        if (Object.hasOwn(value, key) && value[key] === undefined) {
+            invalid(`its ${label} has an undefined ${key}`);
+        }
+    }
+    return value;
+}
+function invalid(reason) {
+    throw new TypeError(`Worker deployment is invalid: ${reason}.`);
+}

package/dist/deployment/worker/response.d.ts

@@ -0,0 +1,104 @@
+import type { WorkerRecord, WorkerRecordWireV1 } from './record.js';
+/** Where a Worker host addresses Services and deployments. */
+export interface WorkerHostingV1 {
+    /**
+     * The DNS name every URL ends with: `https://<service>.<routingDomain>` serves a Service's
+     * current deployment, `https://<label>.<routingDomain>` one deployment.
+     */
+    readonly routingDomain: string;
+}
+/** What a host lists: the deployments of the caller's Services, optionally of one project or environment. */
+export interface WorkerDeploymentListRequestV1 {
+    readonly project?: string;
+    readonly environment?: string;
+}
+/** The lifecycle of one deployment at its host. */
+export type WorkerDeploymentState = 'deploying' | 'active' | 'retiring' | 'retired' | 'failed';
+/**
+ * What a host knows of one deployment. It names a deployment by its label and URL, never by a
+ * provider version. A host keeps every deployment until it is retired: it has no preview, expiry or
+ * last call.
+ */
+export interface WorkerDeploymentSummaryV1 {
+    /** The host's id of the deployment (a node id on Admin's Services). */
+    readonly id: string;
+    readonly url: string;
+    readonly label: string;
+    /** The host's id of the Service this deployment is a version of. */
+    readonly serviceId: string;
+    /** The name of that Service: the first part of the label. */
+    readonly service: string;
+    readonly project: string;
+    readonly environment: string;
+    /** Who owns the Service (an Identity node path on Admin's Services). */
+    readonly owner: string;
+    readonly state: WorkerDeploymentState;
+    /** Whether the Service's stable URL serves this deployment. */
+    readonly current: boolean;
+    readonly createdAt: string;
+    /** When its retirement began; present once it is `retiring`. */
+    readonly retiredAt?: string;
+    readonly buildDigest: string;
+    /** The digest of its `WorkerConfigurationV1`. */
+    readonly configuration: string;
+    /** The RFC 7638 thumbprint of its key, when its configuration asked for a signing identity. */
+    readonly signingKeyId?: string;
+    /** The record it serves, when its configuration asked for one. */
+    readonly record?: WorkerRecordWireV1;
+}
+/** One summary with its record decoded. */
+export type WorkerDeploymentSummary = Omit<WorkerDeploymentSummaryV1, 'record'> & {
+    readonly record?: WorkerRecord;
+};
+/** Why a host refused to host one Worker release. A refusal changed nothing (see each reason). */
+export type WorkerDeploymentRejectionReason = 'invalid-deployment' | 'address-mismatch' | 'build-mismatch' | 'service-owned-elsewhere' | 'deployment-conflict' | 'deployment-retired' | 'hosting-unavailable' | 'service-unavailable';
+export declare const WORKER_DEPLOYMENT_REJECTIONS: readonly WorkerDeploymentRejectionReason[];
+/**
+ * `WorkerDeploymentResponseV1`: a deployment `created` with the request's secrets `bound` to it,
+ * or `reused` with its declared secrets rewritten in place (`updated`) or left `unchanged`, or a
+ * refusal. A refusal changed nothing, except that a `service-unavailable` may follow effects (a
+ * creation that lost its lease after uploading, an in-place rewrite that wrote part of the
+ * values): rerunning the same deploy converges.
+ */
+export type WorkerDeploymentResponseV1 = {
+    readonly kind: 'deployed';
+    readonly state: 'created' | 'reused';
+    readonly secrets: {
+        readonly state: 'bound' | 'updated' | 'unchanged';
+    };
+    readonly deployment: WorkerDeploymentSummaryV1;
+} | WorkerDeploymentRejection;
+export interface WorkerDeploymentRejection {
+    readonly kind: 'rejected';
+    readonly reason: WorkerDeploymentRejectionReason;
+    readonly message: string;
+    /** When a retry may succeed, for a refusal that only waits on another operation. */
+    readonly retryAfter?: string;
+}
+/** One decoded answer of a deploy. */
+export type WorkerDeploymentResult = {
+    readonly kind: 'deployed';
+    readonly state: 'created' | 'reused';
+    readonly secrets: {
+        readonly state: 'bound' | 'updated' | 'unchanged';
+    };
+    readonly deployment: WorkerDeploymentSummary;
+} | WorkerDeploymentRejection;
+/**
+ * Admit the answer of a host's `hosting`: its routing domain. The `addressing: 'opaque'` an older
+ * Services answers beside it is admitted and dropped: every Service name is opaque.
+ */
+export declare function decodeWorkerHosting(input: unknown): WorkerHostingV1;
+/**
+ * Admit the answer of a deploy exactly: a deployment whose state reports the secret state it
+ * pairs with, or a refusal a host can give.
+ */
+export declare function decodeWorkerDeploymentResponse(input: unknown): WorkerDeploymentResult;
+/** Admit the answer of a host's `list`: the summaries of the caller's deployments, in its order. */
+export declare function decodeWorkerDeploymentList(input: unknown): readonly WorkerDeploymentSummary[];
+/**
+ * Admit one summary exactly: node ids and names a person can read, a label whose first part is
+ * the Service's name, the URL of that label, a known state, instants, digests, and a record that
+ * decodes.
+ */
+export declare function decodeWorkerDeploymentSummary(input: unknown): WorkerDeploymentSummary;