@datalayer/agent-runtimes 1.0.29 → 1.3.11

package/lib/api/runtimes/environments.js

@@ -5,25 +5,657 @@
 /**
  * Computing environments API functions for the Datalayer platform.
  *
- * Provides functions for managing computing environment configurations.
+ * `GET /environments` lists the platform's environments and the user
+ * environments the caller may use. The registry beside it (PLAN_ENV.md,
+ * section 9, served by Runtimes since E1-01) creates environments, their
+ * versions, builds and artifacts, and serves build logs. The specification a
+ * version carries is typed from the JSON Schema `code-sandboxes` exports
+ * (D-14), in `models/environments.generated.ts`.
+ *
+ * A conditional write names the record it replaces with `If-Match`, the
+ * `etag` every record carries. A keyed create is replayed with the same
+ * `Idempotency-Key`. Every call may carry the caller's `X-Correlation-Id`,
+ * which a refusal answers in its section 10 body: `asEnvironmentsError` reads
+ * that body from the error a call rejects with.
  *
  * @module api/runtimes/environments
  */
 import { requestDatalayerAPI } from '@datalayer/core/lib/api/DatalayerApi';
 import { API_BASE_PATHS, DEFAULT_SERVICE_URLS, } from '@datalayer/core/lib/api/constants';
-import { validateToken } from '@datalayer/core/lib/api/utils/validation';
+import { validateRequiredString, validateToken, } from '@datalayer/core/lib/api/utils/validation';
+const registryUrl = (baseUrl, path, query = {}) => {
+    const params = new URLSearchParams();
+    for (const [name, value] of Object.entries(query)) {
+        if (value !== undefined && value !== '') {
+            params.set(name, String(value));
+        }
+    }
+    const search = params.toString();
+    return `${baseUrl}${API_BASE_PATHS.RUNTIMES}${path}${search ? `?${search}` : ''}`;
+};
+const segment = (value, label) => {
+    validateRequiredString(value, label);
+    return encodeURIComponent(value);
+};
+const send = (token, method, url, options, body) => {
+    const headers = {};
+    if (options.ifMatch) {
+        headers['If-Match'] = options.ifMatch;
+    }
+    if (options.idempotencyKey) {
+        headers['Idempotency-Key'] = options.idempotencyKey;
+    }
+    if (options.correlationId) {
+        headers['X-Correlation-Id'] = options.correlationId;
+    }
+    return requestDatalayerAPI({
+        url,
+        method,
+        token,
+        headers,
+        signal: options.signal,
+        ...(body === undefined ? {} : { body }),
+    });
+};
+/**
+ * The section 10 body of a refusal, from the error a call rejected with.
+ *
+ * @param error - What an environments call rejected with
+ * @returns The body, with its `code` and `correlationId`; `undefined` when the
+ *   error is not a refusal that carries one
+ */
+export const asEnvironmentsError = async (error) => {
+    const response = error
+        ?.response;
+    if (typeof response?.json !== 'function') {
+        return undefined;
+    }
+    try {
+        const body = await response.json();
+        return body &&
+            typeof body === 'object' &&
+            typeof body.code === 'string'
+            ? body
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
 /**
- * List all available computing environments.
+ * List the environments the caller may use: the platform's, then its own and
+ * its organizations'.
  * @param token - Authentication token
  * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
- * @returns Promise resolving to list of available environments
+ * @param query - Filters, and the cursor of the page to read
+ * @param options - Correlation id and abort signal
+ * @returns Promise resolving to one page of environments
  * @throws {Error} If authentication token is missing or invalid
  */
-export const listEnvironments = async (token, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+export const listEnvironments = async (token, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES, query = {}, options = {}) => {
     validateToken(token);
-    return requestDatalayerAPI({
-        url: `${baseUrl}${API_BASE_PATHS.RUNTIMES}/environments`,
-        method: 'GET',
-        token,
+    return send(token, 'GET', registryUrl(baseUrl, '/environments', { ...query }), options);
+};
+/**
+ * Create a user environment, for the caller's account or an organization it owns.
+ * @param token - Authentication token
+ * @param request - Its name, and optionally title, description, visibility and owner
+ * @param options - Idempotency key, correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the environment created, or the one a replayed key created
+ */
+export const createEnvironment = async (token, request, options = {}, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    return send(token, 'POST', registryUrl(baseUrl, '/environments'), options, request);
+};
+/**
+ * Get a user environment.
+ * @param token - Authentication token
+ * @param environmentUid - The environment's uid
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the environment
+ */
+export const getEnvironment = async (token, environmentUid, options = {}, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    return send(token, 'GET', registryUrl(baseUrl, `/environments/${segment(environmentUid, 'Environment UID')}`), options);
+};
+/**
+ * Change an environment's title, description or visibility.
+ * @param token - Authentication token
+ * @param environmentUid - The environment's uid
+ * @param changes - The fields to change
+ * @param ifMatch - The `etag` of the environment read; a stale one is refused with 412
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the environment changed
+ */
+export const updateEnvironment = async (token, environmentUid, changes, ifMatch, options = {}, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    validateRequiredString(ifMatch, 'If-Match');
+    return send(token, 'PATCH', registryUrl(baseUrl, `/environments/${segment(environmentUid, 'Environment UID')}`), { ...options, ifMatch }, changes);
+};
+/**
+ * Delete an environment, softly. Refused with 409 `DL_ENV_CONFLICT` while a
+ * version is promoted, an artifact is referenced, or a runtime still runs one
+ * of its artifacts, whoever launched it: the refusal's `detail` is an
+ * `IEnvironmentDeletionConflict`, whose `runtimes` name each one (E1-15).
+ * Refused with 503 `DL_ENV_UNAVAILABLE` when the service cannot read which
+ * runtimes run it; nothing is deleted then either.
+ * @param token - Authentication token
+ * @param environmentUid - The environment's uid
+ * @param options - If-Match, correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving once the environment is deleted
+ */
+export const deleteEnvironment = async (token, environmentUid, options = {}, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    await send(token, 'DELETE', registryUrl(baseUrl, `/environments/${segment(environmentUid, 'Environment UID')}`), options);
+};
+/**
+ * Archive an environment: kept and readable, no longer offered for launches.
+ * @param token - Authentication token
+ * @param environmentUid - The environment's uid
+ * @param options - If-Match, correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the environment archived
+ */
+export const archiveEnvironment = async (token, environmentUid, options = {}, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    return send(token, 'POST', registryUrl(baseUrl, `/environments/${segment(environmentUid, 'Environment UID')}/archive`), options);
+};
+/**
+ * Promote a version, or none with `versionUid: null`; a rollback is the same
+ * call with an older version, and builds nothing (E1-15).
+ *
+ * A partially ready version is promoted only when
+ * `acknowledgeUnavailableVariants` names exactly its unavailable variants:
+ * otherwise 409 `DL_ENV_CONFLICT`, whose `detail` is an
+ * `IEnvironmentPromotionConflict` naming them. The promotion is recorded on
+ * the version, as its `promotion`. Asking again for the version already
+ * promoted writes nothing and answers the environment, even with a stale
+ * `If-Match`; asking for another with a stale one is refused with 412.
+ * @param token - Authentication token
+ * @param environmentUid - The environment's uid
+ * @param request - `{versionUid, acknowledgeUnavailableVariants}`
+ * @param ifMatch - The `etag` of the environment read; a stale one is refused with 412
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the environment, naming its promoted version
+ */
+export const promoteEnvironmentVersion = async (token, environmentUid, request, ifMatch, options = {}, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    validateRequiredString(ifMatch, 'If-Match');
+    return send(token, 'PUT', registryUrl(baseUrl, `/environments/${segment(environmentUid, 'Environment UID')}/promoted-version`), { ...options, ifMatch }, request);
+};
+/**
+ * Create a draft version of an environment from a specification.
+ * @param token - Authentication token
+ * @param environmentUid - The environment's uid
+ * @param request - `{spec, label}`
+ * @param options - Idempotency key, correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the draft, or the one a replayed key created
+ */
+export const createEnvironmentVersion = async (token, environmentUid, request, options = {}, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    return send(token, 'POST', registryUrl(baseUrl, `/environments/${segment(environmentUid, 'Environment UID')}/versions`), options, request);
+};
+/**
+ * List an environment's versions, newest first.
+ * @param token - Authentication token
+ * @param environmentUid - The environment's uid
+ * @param page - The cursor of the page to read, and its size
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to one page of versions
+ */
+export const listEnvironmentVersions = async (token, environmentUid, page = {}, options = {}, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    return send(token, 'GET', registryUrl(baseUrl, `/environments/${segment(environmentUid, 'Environment UID')}/versions`, { ...page }), options);
+};
+/**
+ * Get a version, with its specification and its status.
+ * @param token - Authentication token
+ * @param versionUid - The version's uid
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the version
+ */
+export const getEnvironmentVersion = async (token, versionUid, options = {}, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    return send(token, 'GET', registryUrl(baseUrl, `/environment-versions/${segment(versionUid, 'Version UID')}`), options);
+};
+/**
+ * Edit a draft's specification or label.
+ * @param token - Authentication token
+ * @param versionUid - The version's uid
+ * @param changes - `{spec, label}`, either or both
+ * @param ifMatch - The `etag` of the version read; a stale one is refused with 412
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the draft changed
+ */
+export const updateEnvironmentVersion = async (token, versionUid, changes, ifMatch, options = {}, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    validateRequiredString(ifMatch, 'If-Match');
+    return send(token, 'PATCH', registryUrl(baseUrl, `/environment-versions/${segment(versionUid, 'Version UID')}`), { ...options, ifMatch }, changes);
+};
+/**
+ * Validate a version: a dry run answering a capability report per variant.
+ * @param token - Authentication token
+ * @param versionUid - The version's uid
+ * @param request - `{variants}`: the version's own variants when absent
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the report
+ */
+export const validateEnvironmentVersion = async (token, versionUid, request = {}, options = {}, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    return send(token, 'POST', registryUrl(baseUrl, `/environment-versions/${segment(versionUid, 'Version UID')}/validate`), options, request);
+};
+/**
+ * Resolve a version into its lock. The service answers 501 until PLAN_ENV.md
+ * E1-04 builds the resolver, whose answer this resolves to.
+ * @param token - Authentication token
+ * @param versionUid - The version's uid
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the service's answer
+ */
+export const resolveEnvironmentVersion = async (token, versionUid, options = {}, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    return send(token, 'POST', registryUrl(baseUrl, `/environment-versions/${segment(versionUid, 'Version UID')}/resolve`), options);
+};
+/**
+ * Queue a build per variant and region.
+ * @param token - Authentication token
+ * @param versionUid - The version's uid
+ * @param request - `{variants, requiredVariants, regions, force}`
+ * @param options - Idempotency key, correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the builds queued, or those a replayed key queued
+ */
+export const createEnvironmentBuilds = async (token, versionUid, request = {}, options = {}, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    return send(token, 'POST', registryUrl(baseUrl, `/environment-versions/${segment(versionUid, 'Version UID')}/builds`), options, request);
+};
+/**
+ * List a version's builds, newest first.
+ * @param token - Authentication token
+ * @param versionUid - The version's uid
+ * @param page - The cursor of the page to read, and its size
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to one page of builds
+ */
+export const listEnvironmentBuilds = async (token, versionUid, page = {}, options = {}, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    return send(token, 'GET', registryUrl(baseUrl, `/environment-versions/${segment(versionUid, 'Version UID')}/builds`, { ...page }), options);
+};
+/**
+ * The sandboxes running a version now: yours by uid, anybody else's counted (E2-19).
+ * @param token - Authentication token
+ * @param versionUid - The version's uid
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the version's live sandboxes
+ */
+export const getEnvironmentVersionSandboxes = async (token, versionUid, options = {}, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    return send(token, 'GET', registryUrl(baseUrl, `/environment-versions/${segment(versionUid, 'Version UID')}/sandboxes`), options);
+};
+/**
+ * An owner's build quotas and what it holds against each (E1-13, E2-19).
+ * @param token - Authentication token
+ * @param owner - The caller's own when empty; an organization's by its uid
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the limits and the holdings
+ */
+export const getEnvironmentQuotas = async (token, owner = {}, options = {}, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    const query = {};
+    if (owner.ownerType) {
+        query.ownerType = owner.ownerType;
+    }
+    if (owner.ownerUid) {
+        query.ownerUid = owner.ownerUid;
+    }
+    return send(token, 'GET', registryUrl(baseUrl, '/environment-quotas', query), options);
+};
+/**
+ * List a version's artifacts, one per variant and region.
+ * @param token - Authentication token
+ * @param versionUid - The version's uid
+ * @param page - The cursor of the page to read, and its size
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to one page of artifacts
+ */
+export const listEnvironmentArtifacts = async (token, versionUid, page = {}, options = {}, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    return send(token, 'GET', registryUrl(baseUrl, `/environment-versions/${segment(versionUid, 'Version UID')}/artifacts`, { ...page }), options);
+};
+/**
+ * Launch a trial sandbox of a ready or partially ready version, before it is
+ * promoted (E1-14).
+ *
+ * Only an owner tries a version. The runtime is launched as `POST /runtimes`
+ * launches one, with the version pinned, a given name saying which version it
+ * tries, and a credits limit no higher than the service's cap. A draft, a
+ * failed or a deprecated version is refused with 409 `DL_ENV_CONFLICT`, and a
+ * version with no artifact on the plane with 422 `DL_ENV_ARTIFACT_MISSING`.
+ * @param token - Authentication token
+ * @param versionUid - The version's uid
+ * @param request - `{creditsLimit}`, lowered to the service's cap when higher
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the runtime launched, its environment naming the version and artifact
+ */
+export const trialEnvironmentVersion = async (token, versionUid, request = {}, options = {}, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    return send(token, 'POST', registryUrl(baseUrl, `/environment-versions/${segment(versionUid, 'Version UID')}/trial`), options, request);
+};
+/**
+ * Publish a promoted version to the public Library (D-12, E2-15).
+ *
+ * Only an owner publishes (D-19), and only a version whose every input is
+ * public — no build secret, only public indexes — and whose Datalayer
+ * artifact passed its scan: otherwise the refusal is `DL_ENV_PUBLICATION_BLOCKED`.
+ * The snapshot frozen is immutable, so publishing the same version again reads
+ * it back and a withdrawal followed by a re-publish restores exactly what was
+ * public.
+ * @param token - Authentication token
+ * @param versionUid - The version's uid
+ * @param options - Optional If-Match, correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the publication, with its immutable snapshot
+ */
+export const publishEnvironmentVersion = async (token, versionUid, options = {}, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    return send(token, 'POST', registryUrl(baseUrl, `/environment-versions/${segment(versionUid, 'Version UID')}/publish`), options);
+};
+/**
+ * Withdraw a version from the public Library; running sandboxes keep it (D-12,
+ * E2-15). The snapshot is kept, so a later publish restores exactly what was
+ * public.
+ * @param token - Authentication token
+ * @param versionUid - The version's uid
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the withdrawn publication
+ */
+export const unpublishEnvironmentVersion = async (token, versionUid, options = {}, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    return send(token, 'POST', registryUrl(baseUrl, `/environment-versions/${segment(versionUid, 'Version UID')}/unpublish`), options);
+};
+/**
+ * A version's public publication and its immutable snapshot (D-12, E2-15), or
+ * a 404 when it is not public. The publication is world-visible, so any
+ * signed-in caller reads it; a version never published, or one withdrawn,
+ * reads 404.
+ * @param token - Authentication token
+ * @param versionUid - The version's uid
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the publication, with its immutable snapshot
+ */
+export const getEnvironmentPublication = async (token, versionUid, options = {}, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    return send(token, 'GET', registryUrl(baseUrl, `/environment-versions/${segment(versionUid, 'Version UID')}/publication`), options);
+};
+/**
+ * Fork a published version into the caller's own private environment (D-12,
+ * E2-15).
+ *
+ * Any signed-in caller forks. The fork is made from the published version's
+ * exact spec and reuses the published Datalayer artifact — the same immutable
+ * reference — when its inputs are unchanged, so it launches without a rebuild;
+ * a fork under a new `name` re-specialises the spec and builds fresh.
+ * @param token - Authentication token
+ * @param versionUid - The published version's uid
+ * @param request - `{name}`: the source environment's name by default
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the fork: its environment, version and reused artifacts
+ */
+export const forkEnvironmentVersion = async (token, versionUid, request = {}, options = {}, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    return send(token, 'POST', registryUrl(baseUrl, `/environment-versions/${segment(versionUid, 'Version UID')}/fork`), options, request);
+};
+/**
+ * Deprecate a version: no new launches, and running sandboxes keep it.
+ * @param token - Authentication token
+ * @param versionUid - The version's uid
+ * @param options - If-Match, correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the version deprecated
+ */
+export const deprecateEnvironmentVersion = async (token, versionUid, options = {}, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    return send(token, 'POST', registryUrl(baseUrl, `/environment-versions/${segment(versionUid, 'Version UID')}/deprecate`), options);
+};
+/**
+ * Get a build.
+ * @param token - Authentication token
+ * @param buildUid - The build's uid
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the build
+ */
+export const getEnvironmentBuild = async (token, buildUid, options = {}, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    return send(token, 'GET', registryUrl(baseUrl, `/environment-builds/${segment(buildUid, 'Build UID')}`), options);
+};
+/**
+ * Read a build's stored log chunks after a cursor: the polling side of D-15.
+ * @param token - Authentication token
+ * @param buildUid - The build's uid
+ * @param page - `cursor`, the sequence of the last chunk read, and the page size
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the chunks, the next cursor, and whether the log is complete
+ */
+export const getEnvironmentBuildLogs = async (token, buildUid, page = {}, options = {}, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    return send(token, 'GET', registryUrl(baseUrl, `/environment-builds/${segment(buildUid, 'Build UID')}/logs`, { ...page }), options);
+};
+/**
+ * Cancel a build that has not ended.
+ * @param token - Authentication token
+ * @param buildUid - The build's uid
+ * @param options - If-Match, correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the build cancelled
+ */
+export const cancelEnvironmentBuild = async (token, buildUid, options = {}, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    return send(token, 'POST', registryUrl(baseUrl, `/environment-builds/${segment(buildUid, 'Build UID')}/cancel`), options);
+};
+/**
+ * Queue the next attempt of a cancelled build, or of one that failed under a
+ * retryable code, once however often it is asked for.
+ *
+ * A retryable failure — a timeout, a quota, a missing artifact, an unmapped
+ * provider failure — reopens its version, `failed` back to `building`. Any
+ * other failure is refused with `DL_ENV_CONFLICT` naming the code: a new
+ * version is what changes it, not another attempt.
+ * @param token - Authentication token
+ * @param buildUid - The build's uid
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the attempt queued
+ */
+export const retryEnvironmentBuild = async (token, buildUid, options = {}, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    return send(token, 'POST', registryUrl(baseUrl, `/environment-builds/${segment(buildUid, 'Build UID')}/retry`), options);
+};
+// -- Following a build's log (D-15) --------------------------------------------
+/** The event the log stream ends with, once the build is terminal and every chunk is sent. */
+export const BUILD_LOG_END_EVENT = 'end';
+/** The service refused to stream the log; asking again would be refused again. */
+export class BuildLogSubscriptionRefused extends Error {
+    status;
+    detail;
+    constructor(status, detail) {
+        super(`Following the build log was refused with ${status}: ${detail}`);
+        this.status = status;
+        this.detail = detail;
+        this.name = 'BuildLogSubscriptionRefused';
+    }
+}
+/** The complete events of what has arrived, and the start of one still arriving. */
+const readServerSentEvents = (buffer) => {
+    const blocks = buffer.replace(/\r\n/g, '\n').split('\n\n');
+    const rest = blocks.pop() ?? '';
+    const events = blocks
+        .filter(block => block.trim() !== '')
+        .map(block => {
+        const framed = { event: 'message', data: '' };
+        const data = [];
+        for (const line of block.split('\n')) {
+            if (line.startsWith(':')) {
+                continue;
+            }
+            const colon = line.indexOf(':');
+            const field = colon === -1 ? line : line.slice(0, colon);
+            const value = colon === -1 ? '' : line.slice(colon + 1).replace(/^ /, '');
+            if (field === 'id') {
+                framed.id = value;
+            }
+            else if (field === 'event') {
+                framed.event = value;
+            }
+            else if (field === 'data') {
+                data.push(value);
+            }
+        }
+        framed.data = data.join('\n');
+        return framed;
     });
+    return { events, rest };
+};
+const pause = (milliseconds, signal) => new Promise(resolve => {
+    if (milliseconds <= 0 || signal?.aborted) {
+        resolve();
+        return;
+    }
+    const timer = setTimeout(resolve, milliseconds);
+    signal?.addEventListener('abort', () => {
+        clearTimeout(timer);
+        resolve();
+    }, { once: true });
+});
+/**
+ * Follow a build's log until the build is terminal (D-15).
+ *
+ * Modelled on core's `subscribeToExecution`: the stream is Server-Sent Events
+ * read with `fetch`, which unlike `EventSource` carries the bearer token. Each
+ * event's id is the sequence of its chunk. A connection that drops, before the
+ * service answered or in the middle of the stream, is resumed with the last id
+ * received as `Last-Event-ID`, so no chunk is repeated; after `maxReconnects`
+ * drops in a row with no chunk between them, `done` rejects. The stream ends
+ * with `end` once the build is terminal and every chunk is sent (E1-16). A
+ * refusal is not retried: `done` rejects with `BuildLogSubscriptionRefused`,
+ * such as the 404 a caller who may not read the build is answered before the
+ * stream opens. An abort ends the subscription quietly.
+ *
+ * @param token - Authentication token
+ * @param buildUid - The build's uid
+ * @param subscribe - The callbacks, the resume point and the reconnect bounds
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns The subscription
+ */
+export const subscribeToBuildLogs = (token, buildUid, subscribe, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    const url = registryUrl(baseUrl, `/environment-builds/${segment(buildUid, 'Build UID')}/logs`, { follow: true });
+    let lastEventId = subscribe.lastEventId;
+    const fetcher = subscribe.fetch ??
+        ((address, init) => fetch(address, init));
+    const maxReconnects = subscribe.maxReconnects ?? 5;
+    const run = async () => {
+        let dropsInARow = 0;
+        for (;;) {
+            const headers = {
+                Accept: 'text/event-stream',
+                Authorization: `Bearer ${token}`,
+            };
+            if (lastEventId) {
+                headers['Last-Event-ID'] = lastEventId;
+            }
+            let response;
+            try {
+                response = await fetcher(url, {
+                    headers,
+                    signal: subscribe.signal,
+                    credentials: 'include',
+                });
+            }
+            catch {
+                if (subscribe.signal?.aborted) {
+                    return;
+                }
+            }
+            if (response && !response.ok) {
+                throw new BuildLogSubscriptionRefused(response.status, await response.text());
+            }
+            let ended = false;
+            if (response?.body) {
+                const reader = response.body.getReader();
+                const decoder = new TextDecoder();
+                let buffer = '';
+                while (!ended) {
+                    let read;
+                    try {
+                        read = await reader.read();
+                    }
+                    catch {
+                        if (subscribe.signal?.aborted) {
+                            return;
+                        }
+                        break;
+                    }
+                    if (read.done) {
+                        break;
+                    }
+                    buffer += decoder.decode(read.value, { stream: true });
+                    const { events, rest } = readServerSentEvents(buffer);
+                    buffer = rest;
+                    for (const framed of events) {
+                        if (framed.event === BUILD_LOG_END_EVENT) {
+                            ended = true;
+                            break;
+                        }
+                        if (framed.data === '') {
+                            continue;
+                        }
+                        const chunk = JSON.parse(framed.data);
+                        if (typeof chunk?.sequence !== 'number') {
+                            continue;
+                        }
+                        lastEventId = framed.id ? framed.id : String(chunk.sequence);
+                        subscribe.onChunk(chunk, lastEventId);
+                        dropsInARow = 0;
+                    }
+                }
+                if (ended) {
+                    await reader.cancel().catch(() => undefined);
+                }
+            }
+            if (ended) {
+                subscribe.onEnd?.();
+                return;
+            }
+            if (subscribe.signal?.aborted) {
+                return;
+            }
+            dropsInARow += 1;
+            if (dropsInARow > maxReconnects) {
+                throw new Error(`The log of build '${buildUid}' dropped ${dropsInARow} times with no chunk in between.`);
+            }
+            await pause(subscribe.reconnectDelayMs ?? 1000, subscribe.signal);
+        }
+    };
+    return { done: run(), lastEventId: () => lastEventId };
 };