@astrale-os/sdk 0.6.0-beta.2 → 0.6.0-beta.20

package/dist/deployment/address/record.d.ts

@@ -0,0 +1,52 @@
+import type { Revision } from '@astrale-os/kernel-dsl/v1/addressing';
+import type { Digest } from '@astrale-os/kernel-protocol/artifact';
+import type { ReleaseDigest } from '@astrale-os/kernel-protocol/release';
+import type { BuildDigest } from '../build/manifest.js';
+export declare const DEPLOYMENT_RECORD_FORMAT = "astrale.deployment-record";
+export declare const DEPLOYMENT_RECORD_VERSION = 1;
+/** The commit a deployment was built from, as the deployer declared it. */
+export interface DeploymentCommitV1 {
+    /** The full commit SHA, 40 hexadecimal digits in either case; git prints it in lower case. */
+    readonly sha: string;
+    /** Whether the tree had changes the commit does not hold. */
+    readonly dirty: boolean;
+    /**
+     * The last release tag before the commit, as `git describe` finds it: its canonical version (the
+     * `v` or `<component>-v` prefix of the tag removed) and the number of commits since.
+     */
+    readonly base?: {
+        readonly version: string;
+        readonly distance: number;
+    };
+}
+/**
+ * What one deploy declares about the deployment it made. The host stores it as declared, beside
+ * what it knows itself, and anyone holding the deployment URL may read it: it is the inventory a
+ * listing and the cleanup read, never something to install from. Any extension is a new record
+ * version.
+ */
+export interface DeploymentRecordV1 {
+    readonly format: typeof DEPLOYMENT_RECORD_FORMAT;
+    readonly version: typeof DEPLOYMENT_RECORD_VERSION;
+    readonly origin: string;
+    readonly environment: string;
+    readonly releaseDigest: ReleaseDigest;
+    readonly buildDigest: BuildDigest;
+    readonly schemaRevision: Revision;
+    /** The full digest of the frozen configuration. */
+    readonly configuration: Digest;
+    /** The provider script, named by the deployment label. */
+    readonly providerScript: string;
+    readonly commit: DeploymentCommitV1 | null;
+}
+/**
+ * Admit one deployment record exactly. Its provider script must be the label its own fields
+ * derive: the line of its origin and environment, readable or opaque, and the content of its build
+ * and configuration digests. A record that claims another deployment's code is refused.
+ *
+ * A host admits the record a deploy declares with this function before it stores it, so every
+ * stored record decodes. A reader that still meets a record this function refuses lists that
+ * deployment from what the host knows, leaving out what is not canonical as a deployment name
+ * does, and never fails the whole listing over it.
+ */
+export declare function acceptDeploymentRecord(input: unknown): DeploymentRecordV1;

package/dist/deployment/address/record.js

@@ -0,0 +1,104 @@
+import { patterns } from '@astrale-os/kernel-dsl/v1/addressing';
+import { isVersion } from '../../platform/versioning/version.js';
+import { ENVIRONMENT_NAME } from '../environment.js';
+import { contentOf, parseDeploymentLabel } from './label.js';
+import { deploymentLine } from './line.js';
+export const DEPLOYMENT_RECORD_FORMAT = 'astrale.deployment-record';
+export const DEPLOYMENT_RECORD_VERSION = 1;
+const DIGEST = /^sha256:[0-9a-f]{64}$/u;
+/** The full hexadecimal SHA-1 of a commit, in either case, as a deployment name reads it. */
+const SHA = /^[0-9a-f]{40}$/iu;
+const ADDRESSINGS = ['readable', 'opaque'];
+/**
+ * Admit one deployment record exactly. Its provider script must be the label its own fields
+ * derive: the line of its origin and environment, readable or opaque, and the content of its build
+ * and configuration digests. A record that claims another deployment's code is refused.
+ *
+ * A host admits the record a deploy declares with this function before it stores it, so every
+ * stored record decodes. A reader that still meets a record this function refuses lists that
+ * deployment from what the host knows, leaving out what is not canonical as a deployment name
+ * does, and never fails the whole listing over it.
+ */
+export function acceptDeploymentRecord(input) {
+    const record = exact(input, [
+        'format',
+        'version',
+        'origin',
+        'environment',
+        'releaseDigest',
+        'buildDigest',
+        'schemaRevision',
+        'configuration',
+        'providerScript',
+        'commit',
+    ]);
+    if (record.format !== DEPLOYMENT_RECORD_FORMAT || record.version !== DEPLOYMENT_RECORD_VERSION) {
+        invalid('format');
+    }
+    if (typeof record.origin !== 'string' || !patterns.origin.test(record.origin))
+        invalid('origin');
+    if (typeof record.environment !== 'string' || !ENVIRONMENT_NAME.test(record.environment)) {
+        invalid('environment');
+    }
+    const origin = record.origin;
+    const environment = record.environment;
+    const buildDigest = digest(record.buildDigest, 'buildDigest');
+    const configuration = digest(record.configuration, 'configuration');
+    if (typeof record.providerScript !== 'string')
+        invalid('providerScript');
+    const label = parseDeploymentLabel(record.providerScript);
+    const lines = ADDRESSINGS.map((addressing) => deploymentLine({ origin, environment, addressing }));
+    if (!lines.includes(label.line) || label.content !== contentOf(buildDigest, configuration)) {
+        throw new TypeError('Deployment record provider script is not the label its fields derive.');
+    }
+    return Object.freeze({
+        format: DEPLOYMENT_RECORD_FORMAT,
+        version: DEPLOYMENT_RECORD_VERSION,
+        origin,
+        environment,
+        releaseDigest: digest(record.releaseDigest, 'releaseDigest'),
+        buildDigest,
+        schemaRevision: digest(record.schemaRevision, 'schemaRevision'),
+        configuration,
+        providerScript: record.providerScript,
+        commit: record.commit === null ? null : commit(record.commit),
+    });
+}
+function commit(input) {
+    const based = input !== null && typeof input === 'object' && Object.hasOwn(input, 'base');
+    const value = exact(input, based ? ['sha', 'dirty', 'base'] : ['sha', 'dirty'], 'commit');
+    if (typeof value.sha !== 'string' || !SHA.test(value.sha))
+        invalid('commit');
+    if (typeof value.dirty !== 'boolean')
+        invalid('commit');
+    if (!based)
+        return Object.freeze({ sha: value.sha, dirty: value.dirty });
+    const base = exact(value.base, ['version', 'distance'], 'commit');
+    if (!isVersion(base.version))
+        invalid('commit');
+    if (!Number.isSafeInteger(base.distance) || base.distance < 0)
+        invalid('commit');
+    return Object.freeze({
+        sha: value.sha,
+        dirty: value.dirty,
+        base: Object.freeze({ version: base.version, distance: base.distance }),
+    });
+}
+function exact(input, keys, member = 'members') {
+    if (input === null ||
+        typeof input !== 'object' ||
+        Array.isArray(input) ||
+        Reflect.ownKeys(input).length !== keys.length ||
+        keys.some((key) => !Object.hasOwn(input, key))) {
+        invalid(member);
+    }
+    return input;
+}
+function digest(input, member) {
+    if (typeof input !== 'string' || !DIGEST.test(input))
+        invalid(member);
+    return input;
+}
+function invalid(member) {
+    throw new TypeError(`Deployment record has invalid ${member}.`);
+}

package/dist/deployment/address/summary.d.ts

@@ -0,0 +1,57 @@
+import type { DeploymentRecordV1 } from './record.js';
+/**
+ * What a host knows of one immutable deployment beside the record its deployer declared: where it
+ * answers, who owns its line, its lifecycle and its retention. It names a deployment by its label
+ * and URL, never by a provider version id. An adapter's `list` returns these; the host owns every
+ * field but `record`, which it stores as declared.
+ */
+export interface DeploymentSummaryV1 {
+    /** The host's own identifier of the deployment (a graph node id on Admin's Services). */
+    readonly id: string;
+    readonly url: string;
+    readonly label: string;
+    readonly line: string;
+    /** The Identity owning the line: a node path on Admin's Services, `platform` on a platform namespace. */
+    readonly owner: string;
+    readonly state: 'deploying' | 'active' | 'retiring' | 'retired' | 'failed';
+    readonly retention: 'preview' | 'published';
+    readonly createdAt: string;
+    readonly lastCallAt?: string;
+    /** A preview's: 30 days after its activation or its last call, whichever is later (AM-123). */
+    readonly expiresAt?: string;
+    readonly retiredAt?: string;
+    readonly retirement?: 'expired' | 'withdrawn';
+    readonly signingKeyId: string;
+    readonly record: DeploymentRecordV1;
+}
+/** The owner every summary of a platform namespace names: the platform holds all of its lines. */
+export declare const PLATFORM_OWNER = "platform";
+/**
+ * `summary:<label>` in the routing KV of a platform dispatch namespace (CT20, AM-131): the
+ * `DeploymentSummaryV1` of one deployment without its record, which stays at `record:<label>`.
+ *
+ * Its writers are the deployer (`cloudflare({ namespace })`), which writes it at activation,
+ * before `record:<label>`, names in it the new key of a script it recreates under the label after
+ * an operator deleted it, and marks it published (`retain`), and the platform retirement tooling
+ * (SV6), which records a withdrawal. So it names the deployment by its label (`id` is the label),
+ * is owned by `platform`, is `active` until withdrawn, and carries no `lastCallAt` or `expiresAt`:
+ * nothing on the platform namespace keeps those clocks, and listings read them from the calls
+ * dataset (AM-133). It never carries a provider version id or a secret digest: an in-place secret
+ * write mints a new version id, which identifies nothing (OPS-2 X1).
+ */
+export type PlatformDeploymentSummaryV1 = Omit<DeploymentSummaryV1, 'record' | 'lastCallAt' | 'expiresAt' | 'state' | 'retirement'> & {
+    readonly state: 'active' | 'retiring' | 'retired';
+    readonly retirement?: 'withdrawn';
+};
+/**
+ * Admit one platform deployment summary exactly. Any member outside its shape is refused, a
+ * provider version id or a clock among them; so is a summary whose id, line or URL is not its
+ * label's, whose owner is not the platform, or whose state and retirement disagree. A reader that
+ * meets a refused summary lists that label apart, never acting on it.
+ */
+export declare function acceptPlatformDeploymentSummary(input: unknown): PlatformDeploymentSummaryV1;
+/**
+ * The canonical JSON (RFC 8785) of one admitted platform summary, as `summary:<label>` holds it:
+ * one summary has one text, so a writer that reads it back compares texts.
+ */
+export declare function encodePlatformDeploymentSummary(summary: PlatformDeploymentSummaryV1): string;

package/dist/deployment/address/summary.js

@@ -0,0 +1,117 @@
+import { json } from '@astrale-os/kernel-dsl/value';
+import { deploymentUrl, parseDeploymentLabel } from './label.js';
+/** The owner every summary of a platform namespace names: the platform holds all of its lines. */
+export const PLATFORM_OWNER = 'platform';
+const REQUIRED = [
+    'id',
+    'url',
+    'label',
+    'line',
+    'owner',
+    'state',
+    'retention',
+    'createdAt',
+    'signingKeyId',
+];
+const RETIREMENT = ['retiredAt', 'retirement'];
+const STATES = ['active', 'retiring', 'retired'];
+const RETENTIONS = ['preview', 'published'];
+/** An instant as `Date.prototype.toISOString` writes it, in UTC. */
+const INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u;
+/** An RFC 7638 JWK thumbprint: the base64url SHA-256 of the public key, 43 characters. */
+const KEY_ID = /^[A-Za-z0-9_-]{43}$/u;
+/**
+ * Admit one platform deployment summary exactly. Any member outside its shape is refused, a
+ * provider version id or a clock among them; so is a summary whose id, line or URL is not its
+ * label's, whose owner is not the platform, or whose state and retirement disagree. A reader that
+ * meets a refused summary lists that label apart, never acting on it.
+ */
+export function acceptPlatformDeploymentSummary(input) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input))
+        invalid('members');
+    const value = input;
+    const keys = Reflect.ownKeys(value);
+    const retired = RETIREMENT.some((key) => Object.hasOwn(value, key));
+    const expected = retired ? [...REQUIRED, ...RETIREMENT] : REQUIRED;
+    if (keys.length !== expected.length || expected.some((key) => !Object.hasOwn(value, key))) {
+        invalid('members');
+    }
+    const label = text(value.label, 'label');
+    let line;
+    try {
+        line = parseDeploymentLabel(label).line;
+    }
+    catch {
+        invalid('label');
+    }
+    if (value.id !== label)
+        invalid('id');
+    if (value.line !== line)
+        invalid('line');
+    const url = text(value.url, 'url');
+    if (!sameDeploymentUrl(url, label))
+        invalid('url');
+    if (value.owner !== PLATFORM_OWNER)
+        invalid('owner');
+    const state = value.state;
+    if (typeof state !== 'string' || !STATES.includes(state))
+        invalid('state');
+    if (retired !== (state !== 'active'))
+        invalid('state');
+    const retention = value.retention;
+    if (typeof retention !== 'string' || !RETENTIONS.includes(retention))
+        invalid('retention');
+    const createdAt = instant(value.createdAt, 'createdAt');
+    const signingKeyId = text(value.signingKeyId, 'signingKeyId');
+    if (!KEY_ID.test(signingKeyId))
+        invalid('signingKeyId');
+    if (retired && value.retirement !== 'withdrawn')
+        invalid('retirement');
+    return Object.freeze({
+        id: label,
+        url,
+        label,
+        line,
+        owner: PLATFORM_OWNER,
+        state: state,
+        retention: retention,
+        createdAt,
+        signingKeyId,
+        ...(retired
+            ? { retiredAt: instant(value.retiredAt, 'retiredAt'), retirement: 'withdrawn' }
+            : {}),
+    });
+}
+/**
+ * The canonical JSON (RFC 8785) of one admitted platform summary, as `summary:<label>` holds it:
+ * one summary has one text, so a writer that reads it back compares texts.
+ */
+export function encodePlatformDeploymentSummary(summary) {
+    return json.serialize(acceptPlatformDeploymentSummary(summary));
+}
+/** Whether `url` is exactly `https://<label>.<routing domain>` for some routing domain. */
+function sameDeploymentUrl(url, label) {
+    const prefix = `https://${label}.`;
+    if (!url.startsWith(prefix))
+        return false;
+    try {
+        return deploymentUrl(label, url.slice(prefix.length)) === url;
+    }
+    catch {
+        return false;
+    }
+}
+function text(input, member) {
+    if (typeof input !== 'string' || input.length === 0)
+        invalid(member);
+    return input;
+}
+function instant(input, member) {
+    const value = text(input, member);
+    if (!INSTANT.test(value) || new Date(value).toISOString() !== value)
+        invalid(member);
+    return value;
+}
+function invalid(member) {
+    throw new TypeError(`Platform deployment summary has invalid ${member}.`);
+}

package/dist/deployment/address/vectors.d.ts

@@ -0,0 +1,60 @@
+import type { Digest } from '@astrale-os/kernel-protocol/artifact';
+import type { BuildManifestV1 } from '../build/manifest.js';
+import type { FrozenConfigurationV1 } from './configuration.js';
+import type { LineAddressing } from './line.js';
+/** One line: what an origin and an environment give, readable and opaque. */
+export interface LineVectorV1 {
+    readonly name: string;
+    readonly origin: string;
+    readonly environment: string;
+    readonly readable: string;
+    readonly fingerprint: string;
+    readonly lines: {
+        readonly readable: string;
+        readonly opaque: string;
+    };
+}
+/**
+ * One portable Worker upload as a host receives it. Module and asset bytes are the UTF-8 encoding
+ * of their `text`.
+ */
+export interface UploadVectorV1 {
+    readonly origin: string;
+    readonly revision: Digest;
+    readonly bundle: Digest;
+    readonly entry: string;
+    readonly modules: readonly {
+        readonly name: string;
+        readonly text: string;
+    }[];
+    readonly assets?: readonly {
+        readonly path: string;
+        readonly text: string;
+    }[];
+}
+/** One deployment: an upload and a configuration on a line, and everything they derive. */
+export interface DeploymentVectorV1 {
+    readonly name: string;
+    readonly origin: string;
+    readonly environment: string;
+    readonly addressing: LineAddressing;
+    readonly routingDomain: string;
+    readonly upload: UploadVectorV1;
+    readonly configuration: FrozenConfigurationV1;
+    readonly expected: {
+        readonly manifest: BuildManifestV1;
+        readonly buildDigest: Digest;
+        readonly configurationDigest: Digest;
+        readonly line: string;
+        readonly content: string;
+        readonly label: string;
+        readonly url: string;
+    };
+}
+export interface DeploymentAddressVectorsV1 {
+    readonly format: 'astrale.deployment.address-vectors';
+    readonly version: 1;
+    readonly lines: readonly LineVectorV1[];
+    readonly deployments: readonly DeploymentVectorV1[];
+}
+export declare const DEPLOYMENT_ADDRESS_VECTORS: DeploymentAddressVectorsV1;