@sequenceholdings/managed-functions 0.2.0 → 0.3.0

package/dist/orm.js

@@ -21,15 +21,19 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var orm_exports = {};
 __export(orm_exports, {
   FunctionOrmError: () => FunctionOrmError,
+  ORM_JSON_SCALARS_HEADER: () => ORM_JSON_SCALARS_HEADER,
+  ORM_LOSSLESS_JSON_SCALARS: () => ORM_LOSSLESS_JSON_SCALARS,
   OrmClientError: () => OrmClientError,
   OrmOperationError: () => OrmOperationError,
-  createFunctionOrmExecutor: () => createFunctionOrmExecutor
+  createFunctionOrmExecutor: () => createFunctionOrmExecutor,
+  createFunctionServiceOrmExecutor: () => createFunctionServiceOrmExecutor
 });
 module.exports = __toCommonJS(orm_exports);
 
 // ../orm/dist/client.js
 var NAMESPACE_PATTERN = /^[a-z][a-z0-9_]{0,40}$/;
 var ORM_DATA_TOKEN_HEADER = "x-sequence-data-token";
+var ORM_SERVICE_DATA_TOKEN_HEADER = "x-sequence-data-token-service";
 var MATERIALIZE_ACTOR = "orm:materialize";
 JSON.stringify({ sub: MATERIALIZE_ACTOR, org: null, roles: [], capabilities: [] });
 var OrmClientError = class extends Error {
@@ -78,6 +82,11 @@ function readOperationResponse({
   }
   return payload.data;
 }
+function validateIdempotencyKey(key) {
+  if (key !== void 0 && !/^[A-Za-z0-9._:-]{1,128}$/.test(key)) {
+    throw new OrmClientError("idempotencyKey must be 1\u2013128 letters, digits, dots, underscores, colons or hyphens");
+  }
+}
 var operationHash = /^sha256:[a-f0-9]{64}$/;
 function readManifestHashes(manifest) {
   if (!isRecord(manifest) || typeof manifest.schemaHash !== "string" || !manifest.schemaHash || !isRecord(manifest.operations)) {
@@ -96,18 +105,25 @@ function createOperationExecutorWithTransport({ namespace, manifest, transport }
   if (typeof namespace !== "string" || !NAMESPACE_PATTERN.test(namespace)) throw new OrmClientError("invalid ORM namespace \u2014 expected a lowercase identifier of at most 41 characters");
   const hashes = readManifestHashes(manifest);
   const knownHashes = new Set(hashes.values());
-  return {
-    async execute(op, variables = {}) {
-      const hash = hashes.get(op) ?? (knownHashes.has(op) ? op : void 0);
-      if (!hash) throw new OrmClientError(`unknown operation "${op}" \u2014 not in the manifest (${hashes.size} known). Re-run seq-studio orm generate.`);
-      if (!isRecord(variables)) throw new OrmClientError("operation variables must be an object");
-      const response = await transport({ namespace, op: hash, variables });
-      if (!response || typeof response.ok !== "boolean" || !Number.isInteger(response.status) || response.status < 100 || response.status > 599 || response.ok !== (response.status >= 200 && response.status < 300)) {
-        throw new OrmOperationError("malformed transport response", null, null);
-      }
-      return readOperationResponse(response);
+  async function execute(op, variables = {}, options = {}) {
+    validateIdempotencyKey(options.idempotencyKey);
+    if (typeof op !== "string" && op.namespace !== namespace) throw new OrmClientError("operation belongs to a different namespace");
+    const selector = typeof op === "string" ? op : op.hash;
+    const hash = hashes.get(selector) ?? (knownHashes.has(selector) ? selector : void 0);
+    if (!hash) throw new OrmClientError(`unknown operation "${op}" \u2014 not in the manifest (${hashes.size} known). Re-run seq-studio orm generate.`);
+    if (!isRecord(variables)) throw new OrmClientError("operation variables must be an object");
+    const response = await transport({
+      namespace,
+      op: hash,
+      variables,
+      ...options.idempotencyKey === void 0 ? {} : { idempotencyKey: options.idempotencyKey }
+    });
+    if (!response || typeof response.ok !== "boolean" || !Number.isInteger(response.status) || response.status < 100 || response.status > 599 || response.ok !== (response.status >= 200 && response.status < 300)) {
+      throw new OrmOperationError("malformed transport response", null, null);
     }
-  };
+    return readOperationResponse(response);
+  }
+  return { execute };
 }
 
 // src/orm.ts
@@ -118,21 +134,20 @@ var FunctionOrmError = class extends Error {
   }
   name = "FunctionOrmError";
 };
-function readToken({ request }) {
+var ORM_JSON_SCALARS_HEADER = "x-sequence-orm-json-scalars";
+var ORM_LOSSLESS_JSON_SCALARS = "lossless-v1";
+function readToken({ request, header, missing }) {
   const { headers } = request;
   let value;
   if (typeof headers.get === "function") {
-    value = headers.get(ORM_DATA_TOKEN_HEADER);
+    value = headers.get(header);
   } else {
-    const matches = Object.entries(headers).filter(([name]) => name.toLowerCase() === ORM_DATA_TOKEN_HEADER);
+    const matches = Object.entries(headers).filter(([name]) => name.toLowerCase() === header);
     if (matches.length > 1) throw invalidContext();
     value = matches[0]?.[1];
   }
   if (value === void 0 || value === null || value === "") {
-    throw new FunctionOrmError(
-      "MISSING_CALLER_CONTEXT",
-      "Caller ORM access is unavailable. Declare the function data binding and invoke it through the platform as a signed-in user."
-    );
+    throw new FunctionOrmError("MISSING_CALLER_CONTEXT", missing);
   }
   if (typeof value !== "string" || value.length > 32768) throw invalidContext();
   return value;
@@ -143,7 +158,7 @@ function invalidContext() {
 function record(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
-function callerExpiry({ token }) {
+function invocationClaims({ token }) {
   const parts = /^([A-Za-z0-9_-]+)\.([A-Za-z0-9_-]{43})$/.exec(token);
   if (!parts?.[1]) throw invalidContext();
   let claims;
@@ -153,10 +168,24 @@ function callerExpiry({ token }) {
     throw invalidContext();
   }
   if (!record(claims) || typeof claims.sub !== "string" || !claims.sub || typeof claims.functionId !== "string" || !claims.functionId || typeof claims.invocationId !== "string" || !claims.invocationId || typeof claims.exp !== "number" || !Number.isSafeInteger(claims.exp) || claims.origin !== void 0 && claims.origin !== "function") throw invalidContext();
+  return { sub: claims.sub, exp: claims.exp, assertedBy: claims.assertedBy };
+}
+function callerExpiry({ token }) {
+  const claims = invocationClaims({ token });
   if (claims.sub.startsWith("service-account|") || claims.sub.endsWith("@clients") || claims.assertedBy != null) {
     throw new FunctionOrmError(
       "UNSUPPORTED_CALLER",
-      "This ORM helper requires a direct human invocation. Service-account and system-runner invocations are not supported."
+      "This ORM helper requires a direct human invocation. For system-runner (Lattice) invocations, use createFunctionServiceOrmExecutor to act as the function's attached service account."
+    );
+  }
+  return claims.exp;
+}
+function serviceExpiry({ token }) {
+  const claims = invocationClaims({ token });
+  if (!claims.sub.startsWith("service-account|") || typeof claims.assertedBy !== "string" || !claims.assertedBy) {
+    throw new FunctionOrmError(
+      "UNSUPPORTED_CALLER",
+      "The service data token does not name the function's attached service account."
     );
   }
   return claims.exp;
@@ -185,40 +214,84 @@ function trustedOrigin({ baseUrl }) {
   }
   return url.origin;
 }
-function createFunctionOrmExecutor({
-  request,
+function createExecutor({
   baseUrl,
   namespace,
   manifest,
-  fetchImpl = globalThis.fetch
+  fetchImpl,
+  token,
+  header,
+  expiresAt,
+  jsonScalars
 }) {
   const origin = trustedOrigin({ baseUrl });
-  const token = readToken({ request });
-  const expiresAt = callerExpiry({ token });
   requireUnexpired({ expiresAt });
   if (typeof fetchImpl !== "function") {
-    throw new FunctionOrmError("INVALID_CONFIGURATION", "Caller ORM access requires a fetch implementation.");
+    throw new FunctionOrmError("INVALID_CONFIGURATION", "Function ORM access requires a fetch implementation.");
+  }
+  if (jsonScalars !== void 0 && jsonScalars !== ORM_LOSSLESS_JSON_SCALARS) {
+    throw new FunctionOrmError("INVALID_CONFIGURATION", `jsonScalars must be ${ORM_LOSSLESS_JSON_SCALARS} when supplied.`);
   }
   return createOperationExecutorWithTransport({
     namespace,
     manifest,
-    transport: async ({ namespace: targetNamespace, op, variables }) => {
+    transport: async ({ namespace: targetNamespace, op, variables, idempotencyKey }) => {
       requireUnexpired({ expiresAt });
       const response = await fetchImpl(`${origin}/_data/v2/${targetNamespace}`, {
         method: "POST",
-        headers: { "Content-Type": "application/json", [ORM_DATA_TOKEN_HEADER]: token },
-        body: JSON.stringify({ op, variables }),
+        headers: {
+          "Content-Type": "application/json",
+          [header]: token,
+          ...jsonScalars ? { [ORM_JSON_SCALARS_HEADER]: jsonScalars } : {}
+        },
+        body: JSON.stringify({ op, variables, idempotencyKey }),
         redirect: "error"
       });
       const body = await response.json().catch(() => null);
+      if (jsonScalars && response.ok && response.headers.get(ORM_JSON_SCALARS_HEADER) !== jsonScalars) {
+        throw new OrmOperationError(
+          `Atlas did not confirm ${jsonScalars} numbers for this ORM response, so its numeric and bigint values may be rounded; update Atlas before relying on exact numbers`,
+          response.status,
+          "LOSSLESS_TRANSPORT_UNAVAILABLE"
+        );
+      }
       return { ok: response.ok, status: response.status, body };
     }
   });
 }
+function createFunctionOrmExecutor({
+  request,
+  fetchImpl = globalThis.fetch,
+  ...options
+}) {
+  trustedOrigin({ baseUrl: options.baseUrl });
+  const token = readToken({
+    request,
+    header: ORM_DATA_TOKEN_HEADER,
+    missing: "Caller ORM access is unavailable. Declare the function data binding and invoke it through the platform as a signed-in user."
+  });
+  return createExecutor({ ...options, fetchImpl, token, header: ORM_DATA_TOKEN_HEADER, expiresAt: callerExpiry({ token }) });
+}
+function createFunctionServiceOrmExecutor({
+  request,
+  fetchImpl = globalThis.fetch,
+  ...options
+}) {
+  trustedOrigin({ baseUrl: options.baseUrl });
+  const token = readToken({
+    request,
+    header: ORM_SERVICE_DATA_TOKEN_HEADER,
+    missing: "Service ORM access is unavailable. Declare service_account and the data binding in managed-function.yml and invoke the function through the platform."
+  });
+  return createExecutor({ ...options, fetchImpl, token, header: ORM_SERVICE_DATA_TOKEN_HEADER, expiresAt: serviceExpiry({ token }) });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   FunctionOrmError,
+  ORM_JSON_SCALARS_HEADER,
+  ORM_LOSSLESS_JSON_SCALARS,
   OrmClientError,
   OrmOperationError,
-  createFunctionOrmExecutor
+  createFunctionOrmExecutor,
+  createFunctionServiceOrmExecutor
 });

package/dist/preflight.d.ts

@@ -0,0 +1,9 @@
+import type { ManagedFunctionLimitCatalog } from './limits';
+import { type ManagedFunctionCapabilities, type PreflightIssue, type PreflightManifest } from './capabilities';
+export declare function preflightManagedFunction({ manifest, limits, capabilities, cliVersion, sdkVersion, }: {
+    manifest: PreflightManifest;
+    limits: ManagedFunctionLimitCatalog | null;
+    capabilities: ManagedFunctionCapabilities | null;
+    cliVersion: string;
+    sdkVersion: string | null;
+}): PreflightIssue[];

package/dist/preflight.js

@@ -0,0 +1,172 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.preflightManagedFunction = preflightManagedFunction;
+const capabilities_1 = require("./capabilities");
+const sdk_range_1 = require("./sdk-range");
+const WORKLOAD_FIELDS = [
+    'memory_mb',
+    'timeout_seconds',
+    'min_instances',
+    'max_instances',
+    'invoke_rate_per_minute',
+    'max_response_bytes',
+    'concurrency',
+];
+function preflightManagedFunction({ manifest, limits, capabilities, cliVersion, sdkVersion, }) {
+    const tooling = capabilities?.tooling ?? capabilities_1.MANAGED_FUNCTION_CAPABILITIES.tooling;
+    const issues = [];
+    checkWorkload({ manifest, limits, tooling, cliVersion, sdkVersion, issues });
+    checkPostgres({ manifest, capabilities, tooling, cliVersion, sdkVersion, issues });
+    checkHeaders({ manifest, capabilities, tooling, cliVersion, sdkVersion, issues });
+    checkSdkTimeout({ manifest, limits, capabilities, tooling, cliVersion, sdkVersion, issues });
+    return issues;
+}
+function issue({ field, problem, limit, tooling, requiredCli, requiredSdk, cliVersion, sdkVersion, }) {
+    const installedSdk = sdkVersion ?? 'not declared';
+    return {
+        field,
+        limit,
+        requiredCli,
+        requiredSdk,
+        message: `${field}: ${problem} Supported limit: ${limit}. ` +
+            `Requires ${tooling.cli.package} >= ${requiredCli} (installed ${cliVersion}) ` +
+            `and ${tooling.sdk.package} >= ${requiredSdk} (installed ${installedSdk}).`,
+    };
+}
+function numericCap(entry) {
+    if (!entry || typeof entry !== 'object')
+        return null;
+    const min = Reflect.get(entry, 'min');
+    const max = Reflect.get(entry, 'max');
+    const unit = Reflect.get(entry, 'unit');
+    if (typeof min !== 'number' || typeof max !== 'number')
+        return null;
+    return { min, max, unit: typeof unit === 'string' ? unit : undefined };
+}
+function checkWorkload({ manifest, limits, tooling, cliVersion, sdkVersion, issues, }) {
+    const workload = limits?.workload;
+    if (!workload)
+        return;
+    const declared = manifest.limits;
+    if (!declared)
+        return;
+    for (const name of WORKLOAD_FIELDS) {
+        const value = declared[name];
+        if (typeof value !== 'number')
+            continue;
+        const cap = numericCap(workload[name]);
+        if (!cap)
+            continue;
+        if (Number.isInteger(value) && value >= cap.min && value <= cap.max)
+            continue;
+        const unit = cap.unit ? ` ${cap.unit}` : '';
+        issues.push(issue({
+            field: `limits.${name}`,
+            problem: `${value} is outside the range this deployment enforces`,
+            limit: `${cap.min} to ${cap.max}${unit}`,
+            tooling,
+            requiredCli: tooling.cli.min,
+            requiredSdk: tooling.sdk.min,
+            cliVersion,
+            sdkVersion,
+        }));
+    }
+    const cpu = declared.cpu;
+    const cpuCap = numericCap(workload.cpu);
+    if (cpu === undefined || cpu === 'auto' || !cpuCap)
+        return;
+    if (typeof cpu === 'number' && Number.isInteger(cpu) && cpu >= cpuCap.min && cpu <= cpuCap.max)
+        return;
+    issues.push(issue({
+        field: 'limits.cpu',
+        problem: `${String(cpu)} is outside the range this deployment enforces`,
+        limit: `${cpuCap.min} to ${cpuCap.max}, or auto`,
+        tooling,
+        requiredCli: tooling.cli.min,
+        requiredSdk: tooling.sdk.min,
+        cliVersion,
+        sdkVersion,
+    }));
+}
+function checkPostgres({ manifest, capabilities, tooling, cliVersion, sdkVersion, issues, }) {
+    const feature = capabilities?.features.postgres_egress;
+    if (!feature)
+        return;
+    const entries = manifest.egress ?? [];
+    entries.forEach((entry, index) => {
+        if (!(0, capabilities_1.isPostgresEgress)(entry))
+            return;
+        const field = `egress[${index}]`;
+        if (!feature.supported) {
+            issues.push(issue({
+                field,
+                problem: 'PostgreSQL egress is not supported by this deployment',
+                limit: 'hostnames, http(s) URLs, and public IPv4 CIDRs',
+                tooling,
+                requiredCli: feature.min_cli,
+                requiredSdk: feature.min_sdk,
+                cliVersion,
+                sdkVersion,
+            }));
+            return;
+        }
+        if ((0, capabilities_1.versionIsOlder)(cliVersion, feature.min_cli)) {
+            issues.push(issue({
+                field,
+                problem: 'this CLI rejects PostgreSQL egress that this deployment supports',
+                limit: feature.limit,
+                tooling,
+                requiredCli: feature.min_cli,
+                requiredSdk: feature.min_sdk,
+                cliVersion,
+                sdkVersion,
+            }));
+        }
+    });
+}
+function needsWideHeaders(manifest) {
+    const data = manifest.capabilities?.data;
+    const storage = manifest.capabilities?.storage;
+    const hasData = !!data && Object.keys(data).length > 0;
+    const hasStorage = !!storage && typeof storage === 'object' && Object.keys(storage).length > 0;
+    return hasData || hasStorage;
+}
+function checkHeaders({ manifest, capabilities, tooling, cliVersion, sdkVersion, issues, }) {
+    const feature = capabilities?.features.http_headers;
+    if (!feature || !needsWideHeaders(manifest))
+        return;
+    const supported = capabilities_1.MANAGED_FUNCTION_CAPABILITIES.features.http_headers.max_bytes;
+    if (feature.max_bytes >= supported)
+        return;
+    issues.push(issue({
+        field: feature.field,
+        problem: `invocation headers for capabilities.data or capabilities.storage exceed ${feature.max_bytes} bytes and will fail with HTTP 431`,
+        limit: feature.limit,
+        tooling,
+        requiredCli: feature.min_cli,
+        requiredSdk: feature.min_sdk,
+        cliVersion,
+        sdkVersion,
+    }));
+}
+function checkSdkTimeout({ manifest, limits, capabilities, tooling, cliVersion, sdkVersion, issues, }) {
+    const timeout = manifest.limits?.timeout_seconds;
+    if (typeof timeout !== 'number' || !sdkVersion)
+        return;
+    const feature = capabilities?.features.invoke_timeout ?? capabilities_1.MANAGED_FUNCTION_CAPABILITIES.features.invoke_timeout;
+    if (!(0, sdk_range_1.sdkConstraintIsOlder)(sdkVersion, feature.min_sdk))
+        return;
+    if (timeout <= feature.legacy_sdk_max_seconds)
+        return;
+    const platformMax = numericCap(limits?.workload?.timeout_seconds)?.max ?? feature.max_seconds;
+    issues.push(issue({
+        field: feature.field,
+        problem: `${timeout} seconds exceeds the installed SDK's ${feature.legacy_sdk_max_seconds} second client cap, behind the platform limit of ${platformMax} seconds`,
+        limit: feature.limit,
+        tooling,
+        requiredCli: feature.min_cli,
+        requiredSdk: feature.min_sdk,
+        cliVersion,
+        sdkVersion,
+    }));
+}