@astrale-os/sdk 0.6.0-beta.4 → 0.6.0-beta.41

package/dist/deployment/release/{publication → served}/views.d.ts

@@ -1,4 +1,4 @@
-import type * as publication from '@astrale-os/kernel-protocol/publication';
+import type * as release from '@astrale-os/kernel-protocol/release';
 import type { Build } from '../../build/index.js';
 import type { Addressing } from '../addressing.js';
-export declare function views(build: Build, addressing: Addressing): readonly publication.ViewBinding[];
+export declare function views(build: Build, addressing: Addressing): readonly release.ViewBinding[];

package/dist/deployment/release/{publication → served}/views.js

@@ -8,7 +8,6 @@ export function views(build, addressing) {
         view: route.view,
         href: new URL(route.path.replace(/^\//u, ''), base).href,
         handshake: route.handshake,
-        ...(route.iframe === undefined ? {} : { iframe: route.iframe }),
         ...(route.host === undefined ? {} : { host: route.host }),
     })));
 }

package/dist/deployment/runtime/admission.d.ts

@@ -1,5 +1,5 @@
 import type { ResolvedRuntimeReference } from './resolve.js';
-/** Prove that a resolved module exports the exact Runtime captured by an Application. */
-export declare function admit<RuntimeValue extends object>(application: {
+/** Prove that a resolved module exports the exact Runtime captured by a Domain definition. */
+export declare function admit<RuntimeValue extends object>(definition: {
     readonly runtime: RuntimeValue;
 }, resolved: ResolvedRuntimeReference): RuntimeValue;

package/dist/deployment/runtime/admission.js

@@ -1,11 +1,11 @@
 import { isResolvedRuntimeReference } from './resolve.js';
-/** Prove that a resolved module exports the exact Runtime captured by an Application. */
-export function admit(application, resolved) {
+/** Prove that a resolved module exports the exact Runtime captured by a Domain definition. */
+export function admit(definition, resolved) {
     if (!isResolvedRuntimeReference(resolved)) {
         throw new TypeError('Resolved Runtime reference is not admitted.');
     }
-    if (resolved.runtime !== application.runtime) {
-        throw new TypeError('Runtime module default export differs from the Application Runtime.');
+    if (resolved.runtime !== definition.runtime) {
+        throw new TypeError('Runtime module default export differs from the Domain Runtime.');
     }
-    return application.runtime;
+    return definition.runtime;
 }

package/dist/deployment/verify/index.d.ts

@@ -1,4 +1,3 @@
-export { preflight as verifyPreflight } from './preflight/index.js';
-export { isPreparedArtifact } from './preflight/index.js';
-export type { PreflightInput } from './preflight/index.js';
-export { readiness as verifyReadiness, verifyDeployment } from './readiness/index.js';
+export { bundle as verifyBundle, isBundle, uploadedBuild as verifyUploadedBuild, } from './preflight/index.js';
+export type { BundleInput } from './preflight/index.js';
+export { readiness as verifyReadiness, readinessPaths } from './readiness/index.js';

package/dist/deployment/verify/index.js

@@ -1,3 +1,2 @@
-export { preflight as verifyPreflight } from './preflight/index.js';
-export { isPreparedArtifact } from './preflight/index.js';
-export { readiness as verifyReadiness, verifyDeployment } from './readiness/index.js';
+export { bundle as verifyBundle, isBundle, uploadedBuild as verifyUploadedBuild, } from './preflight/index.js';
+export { readiness as verifyReadiness, readinessPaths } from './readiness/index.js';

package/dist/deployment/verify/preflight/bundle.d.ts

@@ -0,0 +1,18 @@
+import type { Bundle, Bundler, BundleSource } from '../../adapter/bundle/index.js';
+import type { Build, BuildDigest } from '../../build/index.js';
+import type { ResolvedRuntimeReference } from '../../runtime/index.js';
+export interface BundleInput<BuildValue extends Build = Build> {
+    readonly build: BuildValue;
+    readonly runtime: ResolvedRuntimeReference;
+    readonly bundler: Pick<Bundler, 'id' | 'version'>;
+    readonly source: BundleSource;
+}
+/** Detach bundler output and identify it by the build digest of its exact bytes. */
+export declare function bundle<const BuildValue extends Build>(input: BundleInput<BuildValue>): Bundle<BuildValue>;
+export declare function isBundle(input: unknown): input is Bundle;
+/**
+ * `deploy` rebuilds (there is no `deploy --from`), so the exact upload of an immutable deployment
+ * must carry the build digest `astrale-domain build` prints for the same tree. A different digest
+ * refuses the deployment.
+ */
+export declare function uploadedBuild(expected: Bundle, uploaded: BuildDigest): void;

package/dist/deployment/verify/preflight/bundle.js

@@ -0,0 +1,71 @@
+import { buildDigest, buildManifest } from '../../build/index.js';
+import { admit as admitRuntime } from '../../runtime/index.js';
+import { build as verifyBuild } from './build.js';
+const admittedBundles = new WeakSet();
+/** Detach bundler output and identify it by the build digest of its exact bytes. */
+export function bundle(input) {
+    verifyBuild(input.build);
+    admitRuntime({ runtime: input.build.runtime }, input.runtime);
+    const source = input.source;
+    if (source === null || typeof source !== 'object' || Array.isArray(source))
+        invalid();
+    if (Reflect.ownKeys(source).some((key) => key !== 'entrypoint' && key !== 'files'))
+        invalid();
+    if (!Array.isArray(source.files) || source.files.length === 0) {
+        throw new TypeError('Bundle files must be a non-empty array.');
+    }
+    const files = source.files.map((file) => {
+        if (file === null || typeof file !== 'object' || Array.isArray(file))
+            invalid();
+        if (Reflect.ownKeys(file).some((key) => key !== 'path' && key !== 'content') ||
+            !(file.content instanceof Uint8Array)) {
+            invalid();
+        }
+        return Object.freeze({ path: file.path, content: new Uint8Array(file.content) });
+    });
+    if (new Set(files.map((file) => file.path)).size !== files.length) {
+        throw new TypeError('Bundle files must have unique paths.');
+    }
+    const root = input.build.schema.compiled.root;
+    const manifest = buildManifest({
+        origin: root.origin,
+        revision: root.revision,
+        bundle: input.build.schema.bundle.ref.digest,
+        bundler: { id: input.bundler.id, version: input.bundler.version },
+        entrypoint: source.entrypoint,
+        files,
+    });
+    const contents = new Map(files.map((file) => [file.path, file.content]));
+    const admitted = Object.freeze({
+        kind: 'bundle',
+        build: input.build,
+        manifest,
+        digest: buildDigest(manifest),
+        entrypoint: manifest.entrypoint,
+        files: Object.freeze(manifest.files.map((file) => {
+            const content = contents.get(file.path);
+            return Object.freeze({ path: file.path, bytes: () => new Uint8Array(content) });
+        })),
+    });
+    admittedBundles.add(admitted);
+    return admitted;
+}
+export function isBundle(input) {
+    return input !== null && typeof input === 'object' && admittedBundles.has(input);
+}
+/**
+ * `deploy` rebuilds (there is no `deploy --from`), so the exact upload of an immutable deployment
+ * must carry the build digest `astrale-domain build` prints for the same tree. A different digest
+ * refuses the deployment.
+ */
+export function uploadedBuild(expected, uploaded) {
+    if (!isBundle(expected))
+        throw new TypeError('Uploaded build check requires an admitted Bundle.');
+    if (uploaded === expected.digest)
+        return;
+    throw new TypeError(`The uploaded code has build digest ${uploaded}, not ${expected.digest} ` +
+        'as `astrale-domain build` gives for this tree.');
+}
+function invalid() {
+    throw new TypeError('Bundle source is invalid.');
+}

package/dist/deployment/verify/preflight/index.d.ts

@@ -1,13 +1,2 @@
-import type { ArtifactSource, PreparedArtifact } from '../../adapter/prepare/index.js';
-import type { Build } from '../../build/index.js';
-import type { ResolvedRuntimeReference } from '../../runtime/index.js';
-export { artifact, isPreparedArtifact } from './artifact.js';
+export { bundle, isBundle, uploadedBuild, type BundleInput } from './bundle.js';
 export { build } from './build.js';
-export { publication } from './publication.js';
-export interface PreflightInput<BuildValue extends Build = Build> {
-    readonly build: BuildValue;
-    readonly runtime: ResolvedRuntimeReference;
-    readonly source: ArtifactSource;
-}
-/** Admit exact deployment material before any provider mutation. */
-export declare function preflight<const BuildValue extends Build>(input: PreflightInput<BuildValue>): PreparedArtifact<BuildValue>;

package/dist/deployment/verify/preflight/index.js

@@ -1,13 +1,2 @@
-import { artifact } from './artifact.js';
-import { build as verifyBuild } from './build.js';
-import { publication as verifyPublication } from './publication.js';
-export { artifact, isPreparedArtifact } from './artifact.js';
+export { bundle, isBundle, uploadedBuild } from './bundle.js';
 export { build } from './build.js';
-export { publication } from './publication.js';
-/** Admit exact deployment material before any provider mutation. */
-export function preflight(input) {
-    verifyBuild(input.build);
-    const prepared = artifact(input.build, input.runtime, input.source);
-    verifyPublication(prepared);
-    return prepared;
-}

package/dist/deployment/verify/readiness/fetch.d.ts

@@ -0,0 +1,13 @@
+export type ReadinessFetch = (input: string, init: {
+    readonly redirect: 'error';
+    readonly signal?: AbortSignal;
+}) => Promise<Response>;
+export interface ReadinessOptions {
+    readonly fetch?: ReadinessFetch;
+    readonly signal?: AbortSignal;
+}
+export declare const MAXIMUM_DOCUMENT_BYTES: number;
+export declare const MAXIMUM_BUNDLE_BYTES: number;
+export declare function fetchRequired(fetcher: ReadinessFetch, url: string, signal: AbortSignal | undefined): Promise<Response>;
+export declare function bounded(response: Response, url: string, maximum: number): Promise<ArrayBuffer>;
+export declare function text(response: Response, url: string, maximum: number): Promise<string>;

package/dist/deployment/verify/readiness/fetch.js

@@ -0,0 +1,26 @@
+export const MAXIMUM_DOCUMENT_BYTES = 1024 * 1024;
+export const MAXIMUM_BUNDLE_BYTES = 16 * 1024 * 1024;
+export async function fetchRequired(fetcher, url, signal) {
+    const response = await fetcher(url, {
+        redirect: 'error',
+        ...(signal === undefined ? {} : { signal }),
+    });
+    if (!response.ok)
+        throw new Error(`GET ${url} returned ${response.status}.`);
+    return response;
+}
+export async function bounded(response, url, maximum) {
+    const bytes = await response.arrayBuffer();
+    if (bytes.byteLength > maximum)
+        throw new Error(`GET ${url} exceeded ${maximum} bytes.`);
+    return bytes;
+}
+export async function text(response, url, maximum) {
+    const bytes = await bounded(response, url, maximum);
+    try {
+        return new TextDecoder('utf-8', { fatal: true, ignoreBOM: false }).decode(bytes);
+    }
+    catch (cause) {
+        throw new Error(`GET ${url} returned invalid UTF-8.`, { cause });
+    }
+}

package/dist/deployment/verify/readiness/identity.d.ts

@@ -1,7 +1,4 @@
-import type { Addressing } from '../../release/index.js';
-import type { ReadinessFetch } from './publication.js';
+import type { IssuerId } from '../../../platform/auth/index.js';
+import type { ReadinessOptions } from './fetch.js';
 /** Verify issuer discovery and at least one admitted signing key at the serving identity. */
-export declare function verifyIdentity(addressing: Addressing, options?: {
-    readonly fetch?: ReadinessFetch;
-    readonly signal?: AbortSignal;
-}): Promise<void>;
+export declare function verifyIdentity(serving: IssuerId, options?: ReadinessOptions): Promise<void>;

package/dist/deployment/verify/readiness/identity.js

@@ -1,10 +1,10 @@
 import { issuer } from '@astrale-os/kernel-protocol';
 const MAXIMUM_IDENTITY_BYTES = 256 * 1024;
 /** Verify issuer discovery and at least one admitted signing key at the serving identity. */
-export async function verifyIdentity(addressing, options = {}) {
+export async function verifyIdentity(serving, options = {}) {
     const fetcher = options.fetch ?? globalThis.fetch;
-    const configurationUrl = new URL(issuer.paths(addressing.issuer).configuration, addressing.issuer);
-    const configuration = issuer.acceptConfiguration(await json(fetcher, configurationUrl.href, options.signal), addressing.issuer);
+    const configurationUrl = new URL(issuer.paths(serving).configuration, serving);
+    const configuration = issuer.acceptConfiguration(await json(fetcher, configurationUrl.href, options.signal), serving);
     const keys = issuer.acceptKeySet(await json(fetcher, configuration.jwks_uri, options.signal), configuration.id_token_signing_alg_values_supported);
     if (keys.keys.length === 0)
         throw new Error('Serving issuer publishes no signing keys.');

package/dist/deployment/verify/readiness/index.d.ts

@@ -1,10 +1,17 @@
 import type { Release } from '../../release/index.js';
-import type { ReadinessFetch } from './publication.js';
-export { verifyDeployment } from './deployment.js';
+import type { ReadinessOptions } from './fetch.js';
 export { verifyIdentity } from './identity.js';
-export { verifyPublication, type ReadinessFetch } from './publication.js';
-/** Read-only verification of one exact live Release and serving identity. */
-export declare function readiness(release: Release, options?: {
-    readonly fetch?: ReadinessFetch;
-    readonly signal?: AbortSignal;
-}): Promise<void>;
+export type { ReadinessFetch, ReadinessOptions } from './fetch.js';
+export { verifyRelease } from './release.js';
+/**
+ * Read-only verification of one exact live Release and its serving identity: an immutable
+ * deployment's release.json (release digest and build digest).
+ */
+/**
+ * The local paths `readiness` reads of one immutable deployment, each answering 200 once the
+ * deployment serves its release: its `release.json`, its Bundle and its issuer documents (the
+ * OpenID configuration and its key set). A host that probes paths before it activates a
+ * deployment probes these.
+ */
+export declare function readinessPaths(deployed: Release): readonly string[];
+export declare function readiness(release: Release, options?: ReadinessOptions): Promise<void>;

package/dist/deployment/verify/readiness/index.js

@@ -1,10 +1,29 @@
+import { issuer } from '@astrale-os/kernel-protocol';
+import * as release from '@astrale-os/kernel-protocol/release';
 import { verifyIdentity } from './identity.js';
-import { verifyPublication } from './publication.js';
-export { verifyDeployment } from './deployment.js';
+import { verifyRelease } from './release.js';
 export { verifyIdentity } from './identity.js';
-export { verifyPublication } from './publication.js';
-/** Read-only verification of one exact live Release and serving identity. */
+export { verifyRelease } from './release.js';
+/**
+ * Read-only verification of one exact live Release and its serving identity: an immutable
+ * deployment's release.json (release digest and build digest).
+ */
+/**
+ * The local paths `readiness` reads of one immutable deployment, each answering 200 once the
+ * deployment serves its release: its `release.json`, its Bundle and its issuer documents (the
+ * OpenID configuration and its key set). A host that probes paths before it activates a
+ * deployment probes these.
+ */
+export function readinessPaths(deployed) {
+    const { configuration, keys } = issuer.paths(deployed.url);
+    return Object.freeze([
+        new URL(release.url(deployed.url)).pathname,
+        new URL(deployed.document.schema.bundle.href).pathname,
+        configuration,
+        keys,
+    ]);
+}
 export async function readiness(release, options = {}) {
-    await verifyPublication(release, options);
-    await verifyIdentity(release.addressing, options);
+    await verifyRelease(release, options);
+    await verifyIdentity(release.url, options);
 }

package/dist/deployment/verify/readiness/release.d.ts

@@ -0,0 +1,8 @@
+import * as release from '@astrale-os/kernel-protocol/release';
+import type { Release } from '../../release/index.js';
+import type { ReadinessOptions } from './fetch.js';
+/**
+ * Fetch and verify the exact live release of one immutable deployment at its `release.json`: its
+ * release digest and the build digest of its code, then its Bundle.
+ */
+export declare function verifyRelease(expected: Release, options?: ReadinessOptions): Promise<release.DomainRelease>;

package/dist/deployment/verify/readiness/release.js

@@ -0,0 +1,22 @@
+import * as release from '@astrale-os/kernel-protocol/release';
+import { bounded, fetchRequired, MAXIMUM_BUNDLE_BYTES, MAXIMUM_DOCUMENT_BYTES, text, } from './fetch.js';
+/**
+ * Fetch and verify the exact live release of one immutable deployment at its `release.json`: its
+ * release digest and the build digest of its code, then its Bundle.
+ */
+export async function verifyRelease(expected, options = {}) {
+    const fetcher = options.fetch ?? globalThis.fetch;
+    const releaseUrl = release.url(expected.url);
+    const response = await fetchRequired(fetcher, releaseUrl, options.signal);
+    const deployed = release.accept(JSON.parse(await text(response, releaseUrl, MAXIMUM_DOCUMENT_BYTES)));
+    if (!release.matchesReference(deployed, release.reference(expected.document))) {
+        throw new Error('Live release differs from the expected Release.');
+    }
+    if (deployed.build.digest !== expected.buildDigest) {
+        throw new Error('Live release build digest differs from the expected build.');
+    }
+    const bundleResponse = await fetchRequired(fetcher, deployed.schema.bundle.href, options.signal);
+    const bytes = new Uint8Array(await bounded(bundleResponse, deployed.schema.bundle.href, MAXIMUM_BUNDLE_BYTES));
+    release.decodeBundle(deployed, bytes);
+    return deployed;
+}

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

@@ -0,0 +1,26 @@
+import type { Digest } from '@astrale-os/kernel-protocol/artifact';
+/**
+ * The name of a project a Worker host keeps Services for: lower-case letters, digits, `.`, `_`
+ * and `-`, starting and ending with a letter or a digit, at most 253 characters. A Domain origin is
+ * one (a Domain deployer names its project by its origin).
+ */
+export declare const PROJECT_NAME: RegExp;
+/**
+ * The name of the Service of one project in one environment: the first 80 bits of
+ * `sha256(utf8(project) ‖ 0x00 ‖ utf8(environment))` in lower-case base32, 16 characters. It is
+ * opaque, so a Service's URL says nothing of whose code it serves, and it is the line fingerprint
+ * of `@astrale-os/sdk/deployment/address` (`lineFingerprint`) when the project is a Domain origin:
+ * a Domain's Service keeps its name.
+ */
+export declare function serviceName(project: string, environment: string): string;
+/**
+ * The label of one Worker deployment, `<service>-<content>`: its Service's name, then the first
+ * 80 bits of `sha256(utf8(buildDigest) ‖ 0x00 ‖ utf8(configurationDigest))` in lower-case base32.
+ * The same code and configuration in the same Service always give the same label, so a redeploy
+ * of a release reuses its deployment; anything else gives another.
+ */
+export declare function workerDeploymentLabel(input: {
+    readonly service: string;
+    readonly buildDigest: Digest;
+    readonly configurationDigest: Digest;
+}): string;

package/dist/deployment/worker/address.js

@@ -0,0 +1,43 @@
+import { first80 } from '../address/fingerprint.js';
+import { deploymentLabel } from '../address/label.js';
+import { ENVIRONMENT_NAME } from '../environment.js';
+/**
+ * The name of a project a Worker host keeps Services for: lower-case letters, digits, `.`, `_`
+ * and `-`, starting and ending with a letter or a digit, at most 253 characters. A Domain origin is
+ * one (a Domain deployer names its project by its origin).
+ */
+export const PROJECT_NAME = /^[a-z0-9](?:[a-z0-9._-]{0,251}[a-z0-9])?$/u;
+/** The longest environment name a Service is named by. */
+const MAXIMUM_ENVIRONMENT_LENGTH = 63;
+/**
+ * The name of the Service of one project in one environment: the first 80 bits of
+ * `sha256(utf8(project) ‖ 0x00 ‖ utf8(environment))` in lower-case base32, 16 characters. It is
+ * opaque, so a Service's URL says nothing of whose code it serves, and it is the line fingerprint
+ * of `@astrale-os/sdk/deployment/address` (`lineFingerprint`) when the project is a Domain origin:
+ * a Domain's Service keeps its name.
+ */
+export function serviceName(project, environment) {
+    if (typeof project !== 'string' || !PROJECT_NAME.test(project)) {
+        throw new TypeError('Worker project must be a lower-case project name.');
+    }
+    if (typeof environment !== 'string' ||
+        environment.length > MAXIMUM_ENVIRONMENT_LENGTH ||
+        !ENVIRONMENT_NAME.test(environment)) {
+        throw new TypeError('Worker environment must be a project environment name.');
+    }
+    return first80(project, environment);
+}
+/**
+ * The label of one Worker deployment, `<service>-<content>`: its Service's name, then the first
+ * 80 bits of `sha256(utf8(buildDigest) ‖ 0x00 ‖ utf8(configurationDigest))` in lower-case base32.
+ * The same code and configuration in the same Service always give the same label, so a redeploy
+ * of a release reuses its deployment; anything else gives another.
+ */
+export function workerDeploymentLabel(input) {
+    for (const digest of [input.buildDigest, input.configurationDigest]) {
+        if (typeof digest !== 'string' || !/^sha256:[0-9a-f]{64}$/u.test(digest)) {
+            throw new TypeError('Worker deployment digests must be sha256 digests.');
+        }
+    }
+    return deploymentLabel(input.service, first80(input.buildDigest, input.configurationDigest));
+}

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

@@ -0,0 +1,60 @@
+import type { Value } from '@astrale-os/kernel-dsl/value';
+import type { Digest } from '@astrale-os/kernel-protocol/artifact';
+/** How Workers loads one module. */
+export type WorkerModuleKind = 'esm' | 'wasm' | 'text' | 'data';
+/** One module of a Worker, by the name the others import it by. */
+export interface WorkerModule {
+    readonly name: string;
+    readonly kind: WorkerModuleKind;
+    readonly bytes: Uint8Array;
+}
+/** One static asset of a Worker, by the absolute URL path it is served at. */
+export interface WorkerAsset {
+    readonly path: string;
+    readonly bytes: Uint8Array;
+    /** The media type the asset is uploaded with; not part of the build digest. */
+    readonly contentType?: string;
+}
+/**
+ * The members of a build manifest its deployer declares: at least its `format` and `version`,
+ * then whatever provenance the deployer identifies its builds by. A host never reads them: it only
+ * digests them with the `entrypoint` and `files` it computes from the uploaded bytes.
+ *
+ * A generic Worker declares `WORKER_BUILD_MANIFEST`. A Domain deployer declares its
+ * `BuildManifestV1` without `entrypoint` and `files` (`format`, `version`, `origin`, `schema`,
+ * `bundler`), so the digest is exactly the Domain's build digest.
+ */
+export type WorkerBuildManifest = Readonly<Record<string, Value>> & {
+    readonly format: string;
+    readonly version: number;
+};
+/** The build manifest members of a Worker that declares no provenance of its own. */
+export declare const WORKER_BUILD_MANIFEST: WorkerBuildManifest;
+/** The code of one Worker: its modules, its main module, its static assets and its manifest. */
+export interface WorkerCode {
+    readonly manifest: WorkerBuildManifest;
+    readonly mainModule: string;
+    readonly modules: readonly WorkerModule[];
+    readonly assets?: readonly WorkerAsset[];
+}
+/**
+ * The build manifest of one Worker: its declared members, its `entrypoint` (the main module) and
+ * its `files`, sorted by path (UTF-16 code units), each `{ path, digest, size }`. A module is the
+ * file of its own name, a static asset `/<path>` the file `assets/<path>`. A module whose kind is
+ * not the one its name implies (`wasm` for a `.wasm` name, `esm` otherwise) also records its
+ * `kind`, so a module loaded another way is another build. The code is admitted first.
+ */
+export declare function workerBuildManifest(code: WorkerCode): Readonly<Record<string, Value>>;
+/**
+ * The build digest of one Worker: `sha256` of the canonical JSON (RFC 8785) of its build manifest.
+ * A host binds it as `ASTRALE_BUILD_DIGEST`; with a Domain's declared members it is the Domain's
+ * build digest.
+ */
+export declare function workerBuildDigest(code: WorkerCode): Digest;
+/**
+ * Admit the code of one Worker: declared manifest members (a `format`, a positive `version`, no
+ * `entrypoint` nor `files`, at most `manifestSize` bytes of canonical JSON), one to `modules`
+ * modules with safe relative names, unique, the main module among them, and at most `assets`
+ * assets at unique canonical absolute paths. Sizes are bounded per file and for the whole Worker.
+ */
+export declare function acceptWorkerCode(code: WorkerCode): WorkerCode;