@astrale-os/sdk 0.6.0-beta.3 → 0.6.0-beta.30

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

@@ -0,0 +1,42 @@
+import type { Digest } from '@astrale-os/kernel-protocol/artifact';
+import type { BuildDigest } from '../build/manifest.js';
+import type { DeploymentConfiguration } from './configuration.js';
+/**
+ * Every deployment label: an optional readable part, the 16-character line fingerprint and the
+ * 16-character content, both lower-case base32. A legacy provider name (a UUID, a stable Worker
+ * name) never matches, so one dispatcher tells the two apart by the label alone. The pattern
+ * bounds no length; `parseDeploymentLabel` also refuses a label longer than the 57 characters
+ * `deploymentLabel` can produce.
+ */
+export declare const DEPLOYMENT_LABEL: RegExp;
+export interface DeploymentLabelParts {
+    readonly line: string;
+    readonly fingerprint: string;
+    readonly content: string;
+}
+/**
+ * The 16-character content of one deployment: the first 80 bits of
+ * `sha256(utf8(buildDigest) ‖ 0x00 ‖ utf8(deploymentConfigurationDigest(configuration)))` in
+ * lower-case base32. It covers the build and the frozen configuration, never a secret: one address
+ * serves one release, and a changed variable gives another address.
+ */
+export declare function deploymentContent(build: BuildDigest, configuration: DeploymentConfiguration): string;
+/** The content of a build and a full configuration digest, as a deployment record holds them. */
+export declare function contentOf(build: BuildDigest, configuration: Digest): string;
+/**
+ * The DNS label of one deployment, `<line>-<content>`: at most 57 characters, below the 63 of a
+ * DNS label.
+ */
+export declare function deploymentLabel(line: string, content: string): string;
+/**
+ * The URL of one deployment under the host's routing domain. It is the issuer of the release the
+ * deployment serves, and no other deployment ever answers at it. The label is admitted as
+ * `parseDeploymentLabel` admits it, so its host never holds a label longer than 57 characters.
+ */
+export declare function deploymentUrl(label: string, routingDomain: string): string;
+/**
+ * Split a deployment label into its line, the line fingerprint and its content. It admits exactly
+ * the labels `deploymentLabel` produces: `DEPLOYMENT_LABEL`, and at most 57 characters, so a line
+ * of at most 40.
+ */
+export declare function parseDeploymentLabel(label: string): DeploymentLabelParts;

package/dist/deployment/address/label.js

@@ -0,0 +1,80 @@
+import { deploymentConfigurationDigest } from './configuration.js';
+import { first80 } from './fingerprint.js';
+/**
+ * Every deployment label: an optional readable part, the 16-character line fingerprint and the
+ * 16-character content, both lower-case base32. A legacy provider name (a UUID, a stable Worker
+ * name) never matches, so one dispatcher tells the two apart by the label alone. The pattern
+ * bounds no length; `parseDeploymentLabel` also refuses a label longer than the 57 characters
+ * `deploymentLabel` can produce.
+ */
+export const DEPLOYMENT_LABEL = /^(?:[a-z0-9]+(?:-[a-z0-9]+)*-)?[a-z2-7]{16}-[a-z2-7]{16}$/u;
+const LINE = /^(?:[a-z0-9]+(?:-[a-z0-9]+)*-)?[a-z2-7]{16}$/u;
+const CONTENT = /^[a-z2-7]{16}$/u;
+const DIGEST = /^sha256:[0-9a-f]{64}$/u;
+const DNS_NAME = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$/u;
+const MAXIMUM_LINE_LENGTH = 40;
+/** A line, a dash and the content: below the 63 characters of a DNS label. */
+const MAXIMUM_LABEL_LENGTH = MAXIMUM_LINE_LENGTH + 17;
+const MAXIMUM_HOST_LENGTH = 253;
+/**
+ * The 16-character content of one deployment: the first 80 bits of
+ * `sha256(utf8(buildDigest) ‖ 0x00 ‖ utf8(deploymentConfigurationDigest(configuration)))` in
+ * lower-case base32. It covers the build and the frozen configuration, never a secret: one address
+ * serves one release, and a changed variable gives another address.
+ */
+export function deploymentContent(build, configuration) {
+    return contentOf(build, deploymentConfigurationDigest(configuration));
+}
+/** The content of a build and a full configuration digest, as a deployment record holds them. */
+export function contentOf(build, configuration) {
+    return first80(digest(build, 'Build digest'), digest(configuration, 'Configuration digest'));
+}
+/**
+ * The DNS label of one deployment, `<line>-<content>`: at most 57 characters, below the 63 of a
+ * DNS label.
+ */
+export function deploymentLabel(line, content) {
+    if (typeof line !== 'string' || line.length > MAXIMUM_LINE_LENGTH || !LINE.test(line)) {
+        throw new TypeError('Deployment line is invalid.');
+    }
+    if (typeof content !== 'string' || !CONTENT.test(content)) {
+        throw new TypeError('Deployment content is invalid.');
+    }
+    return `${line}-${content}`;
+}
+/**
+ * The URL of one deployment under the host's routing domain. It is the issuer of the release the
+ * deployment serves, and no other deployment ever answers at it. The label is admitted as
+ * `parseDeploymentLabel` admits it, so its host never holds a label longer than 57 characters.
+ */
+export function deploymentUrl(label, routingDomain) {
+    parseDeploymentLabel(label);
+    if (typeof routingDomain !== 'string' || !DNS_NAME.test(routingDomain)) {
+        throw new TypeError('Deployment routing domain must be a lower-case DNS name.');
+    }
+    const host = `${label}.${routingDomain}`;
+    if (host.length > MAXIMUM_HOST_LENGTH) {
+        throw new TypeError('Deployment host exceeds the length of a DNS name.');
+    }
+    return `https://${host}`;
+}
+/**
+ * Split a deployment label into its line, the line fingerprint and its content. It admits exactly
+ * the labels `deploymentLabel` produces: `DEPLOYMENT_LABEL`, and at most 57 characters, so a line
+ * of at most 40.
+ */
+export function parseDeploymentLabel(label) {
+    if (typeof label !== 'string' ||
+        label.length > MAXIMUM_LABEL_LENGTH ||
+        !DEPLOYMENT_LABEL.test(label)) {
+        throw new TypeError('Deployment label is invalid.');
+    }
+    const line = label.slice(0, -17);
+    return Object.freeze({ line, fingerprint: line.slice(-16), content: label.slice(-16) });
+}
+function digest(input, label) {
+    if (typeof input !== 'string' || !DIGEST.test(input)) {
+        throw new TypeError(`${label} is invalid.`);
+    }
+    return input;
+}

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

@@ -0,0 +1,29 @@
+/**
+ * How a line reads. Platform lines are `readable` (`agencies-staging-354iwg4avm6wdmrs`); tenant
+ * lines are `opaque`, their fingerprint alone, so a hosted address says nothing of whose code it
+ * serves. Both derive from the same inputs, never from stored state.
+ */
+export type LineAddressing = 'readable' | 'opaque';
+export interface DeploymentLineInput {
+    readonly origin: string;
+    readonly environment: string;
+    readonly addressing: LineAddressing;
+}
+/**
+ * The 16-character fingerprint of the line of `(origin, environment)`: the first 80 bits of
+ * `sha256(utf8(origin) ‖ 0x00 ‖ utf8(environment))` in lower-case base32. It alone makes a line
+ * unique; the readable part in front of it is cosmetic.
+ */
+export declare function lineFingerprint(origin: string, environment: string): string;
+/**
+ * The cosmetic part of a readable line: the first label of the origin (12 characters at most) and
+ * the environment (10 at most), lower case, each run of characters outside `[a-z0-9]` replaced by
+ * one dash and dashes removed at both edges. Neither part is ever empty: an origin label and an
+ * environment name both start with a letter or a digit.
+ */
+export declare function readablePart(origin: string, environment: string): string;
+/**
+ * The line every deployment of one origin in one environment shares: `<readable>-<fingerprint>`
+ * when readable, the fingerprint alone when opaque. At most 40 characters.
+ */
+export declare function deploymentLine(input: DeploymentLineInput): string;

package/dist/deployment/address/line.js

@@ -0,0 +1,53 @@
+import { patterns } from '@astrale-os/kernel-dsl/v1/addressing';
+import { ENVIRONMENT_NAME } from '../environment.js';
+import { first80 } from './fingerprint.js';
+/**
+ * The 16-character fingerprint of the line of `(origin, environment)`: the first 80 bits of
+ * `sha256(utf8(origin) ‖ 0x00 ‖ utf8(environment))` in lower-case base32. It alone makes a line
+ * unique; the readable part in front of it is cosmetic.
+ */
+export function lineFingerprint(origin, environment) {
+    admitLine(origin, environment);
+    return first80(origin, environment);
+}
+/**
+ * The cosmetic part of a readable line: the first label of the origin (12 characters at most) and
+ * the environment (10 at most), lower case, each run of characters outside `[a-z0-9]` replaced by
+ * one dash and dashes removed at both edges. Neither part is ever empty: an origin label and an
+ * environment name both start with a letter or a digit.
+ */
+export function readablePart(origin, environment) {
+    admitLine(origin, environment);
+    return `${normalize(origin.split('.')[0], 12)}-${normalize(environment, 10)}`;
+}
+/**
+ * The line every deployment of one origin in one environment shares: `<readable>-<fingerprint>`
+ * when readable, the fingerprint alone when opaque. At most 40 characters.
+ */
+export function deploymentLine(input) {
+    if (input === null || typeof input !== 'object') {
+        throw new TypeError('Deployment line input is invalid.');
+    }
+    const fingerprint = lineFingerprint(input.origin, input.environment);
+    if (input.addressing === 'opaque')
+        return fingerprint;
+    if (input.addressing !== 'readable') {
+        throw new TypeError('Deployment line addressing must be readable or opaque.');
+    }
+    return `${readablePart(input.origin, input.environment)}-${fingerprint}`;
+}
+function admitLine(origin, environment) {
+    if (typeof origin !== 'string' || !patterns.origin.test(origin)) {
+        throw new TypeError('Deployment origin must be a Domain origin.');
+    }
+    if (typeof environment !== 'string' || !ENVIRONMENT_NAME.test(environment)) {
+        throw new TypeError('Deployment environment must be a project environment name.');
+    }
+}
+function normalize(input, length) {
+    return input
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/gu, '-')
+        .slice(0, length)
+        .replace(/^-+|-+$/gu, '');
+}

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

@@ -0,0 +1,73 @@
+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 media type of a `DeploymentRecordV1` document: what a Domain deployer publishes it with, and
+ * what a host serves it with at `/.well-known/astrale/deployment.json`.
+ */
+export declare const DEPLOYMENT_RECORD_MEDIA_TYPE = "application/vnd.astrale.deployment-record+json;v=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;
+/** The document of one record: what a Domain deployer publishes and a host serves verbatim. */
+export interface DeploymentRecordDocument {
+    readonly contentType: string;
+    readonly bytes: Uint8Array;
+}
+/**
+ * The document of one record, as a Domain deployer publishes it: the record admitted, as the
+ * UTF-8 bytes of its RFC 8785 canonical JSON, with `DEPLOYMENT_RECORD_MEDIA_TYPE`. One record has
+ * one document, byte for byte, whoever writes it.
+ */
+export declare function encodeDeploymentRecord(record: DeploymentRecordV1): DeploymentRecordDocument;
+/**
+ * Admit the document of one record: `DEPLOYMENT_RECORD_MEDIA_TYPE`, and UTF-8 JSON whose value
+ * `acceptDeploymentRecord` admits. Anything else throws.
+ */
+export declare function decodeDeploymentRecord(document: DeploymentRecordDocument): DeploymentRecordV1;

package/dist/deployment/address/record.js

@@ -0,0 +1,138 @@
+import { patterns } from '@astrale-os/kernel-dsl/v1/addressing';
+import { json } from '@astrale-os/kernel-dsl/value';
+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;
+/**
+ * The media type of a `DeploymentRecordV1` document: what a Domain deployer publishes it with, and
+ * what a host serves it with at `/.well-known/astrale/deployment.json`.
+ */
+export const DEPLOYMENT_RECORD_MEDIA_TYPE = 'application/vnd.astrale.deployment-record+json;v=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),
+    });
+}
+/**
+ * The document of one record, as a Domain deployer publishes it: the record admitted, as the
+ * UTF-8 bytes of its RFC 8785 canonical JSON, with `DEPLOYMENT_RECORD_MEDIA_TYPE`. One record has
+ * one document, byte for byte, whoever writes it.
+ */
+export function encodeDeploymentRecord(record) {
+    return Object.freeze({
+        contentType: DEPLOYMENT_RECORD_MEDIA_TYPE,
+        bytes: new TextEncoder().encode(json.serialize(acceptDeploymentRecord(record))),
+    });
+}
+/**
+ * Admit the document of one record: `DEPLOYMENT_RECORD_MEDIA_TYPE`, and UTF-8 JSON whose value
+ * `acceptDeploymentRecord` admits. Anything else throws.
+ */
+export function decodeDeploymentRecord(document) {
+    if (document?.contentType !== DEPLOYMENT_RECORD_MEDIA_TYPE) {
+        throw new TypeError('Deployment record document has another media type.');
+    }
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder('utf-8', { fatal: true, ignoreBOM: false }).decode(document.bytes));
+    }
+    catch (cause) {
+        throw new TypeError('Deployment record document is not UTF-8 JSON.', { cause });
+    }
+    return acceptDeploymentRecord(value);
+}
+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,30 @@
+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 and its lifecycle. 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, the label on a dispatch namespace). */
+    readonly id: string;
+    readonly url: string;
+    readonly label: string;
+    readonly line: string;
+    /** Who owns the line: a node path on Admin's Services, the dispatch namespace's name on Cloudflare. */
+    readonly owner: string;
+    readonly state: 'deploying' | 'active' | 'retiring' | 'retired' | 'failed';
+    /**
+     * `published` on Admin's Services, which keeps every deployment until it is retired. Absent on a
+     * dispatch namespace, which keeps no retention.
+     */
+    readonly retention?: 'published';
+    /** When the host created it; absent when the host no longer knows (its script is gone). */
+    readonly createdAt?: string;
+    readonly retiredAt?: string;
+    /** `withdrawn` once its owner retired it. */
+    readonly retirement?: 'withdrawn';
+    /** The RFC 7638 thumbprint of its key; absent when the host no longer knows (its script is gone). */
+    readonly signingKeyId?: string;
+    readonly record: DeploymentRecordV1;
+}

package/dist/deployment/address/summary.js

@@ -0,0 +1 @@
+export {};

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;