@hypequery/deployment 0.5.1 → 0.7.0

package/README.md

@@ -223,7 +223,17 @@ import {
 
 const supervisor = createDeploymentRuntimeSupervisor({
   materializer,
-  factory: createNodeWorkerDeploymentRuntimeFactory(),
+  factory: createNodeWorkerDeploymentRuntimeFactory({
+    async resolveEnvironment(snapshot, { signal }) {
+      const connection = await resolveClickHouseConnection(snapshot.target, { signal });
+      return {
+        CLICKHOUSE_URL: connection.url,
+        CLICKHOUSE_DATABASE: connection.database,
+        CLICKHOUSE_USERNAME: connection.username,
+        CLICKHOUSE_PASSWORD: connection.password,
+      };
+    },
+  }),
 });
 
 await supervisor.reconcile({ project: 'analytics', environment: 'production' });
@@ -241,6 +251,19 @@ materialized bytes in worker threads and removes their temporary files on
 shutdown. Provider factories can implement Python, process, container, or
 remote-sandbox isolation behind the same lifecycle interface.
 
+`resolveEnvironment(snapshot, { signal })` lets a provider resolve secrets and
+configuration for one immutable deployment target before its worker imports any
+artifact. When configured, the returned string record replaces the inherited
+process environment for that worker, so concurrent targets do not need to
+mutate shared `process.env`. Returning an empty record creates a worker with an
+empty environment. Omitting the resolver preserves Node's default environment
+inheritance for existing single-host integrations.
+
+Resolvers should return the smallest environment the deployment needs and
+honour the startup abort signal during external secret-store calls. Environment
+resolution failure prevents the candidate from becoming ready and removes its
+temporary artifact bytes.
+
 The reference worker is a lifecycle boundary, not a hostile-code security
 sandbox. Only trusted deployment code should use it directly.
 

package/dist/bundle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../src/bundle.ts"],"names":[],"mappings":"AAQA,OAAO,EAKL,KAAK,gCAAgC,EACrC,KAAK,0BAA0B,EAChC,MAAM,qBAAqB,CAAC;AAE7B,eAAO,MAAM,0BAA0B,gBAAgB,CAAC;AACxD,eAAO,MAAM,0BAA0B,oBAAoB,CAAC;AAE5D,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,gCAAgC,CAAC;IACpD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,0BAA0B,CAAC;CAC/C;AAoKD,wBAAsB,sBAAsB,CAC1C,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,wBAAwB,CAAC,CA2DnC"}
+{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../src/bundle.ts"],"names":[],"mappings":"AAQA,OAAO,EAKL,KAAK,gCAAgC,EACrC,KAAK,0BAA0B,EAChC,MAAM,qBAAqB,CAAC;AAE7B,eAAO,MAAM,0BAA0B,gBAAgB,CAAC;AACxD,eAAO,MAAM,0BAA0B,oBAAoB,CAAC;AAE5D,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,gCAAgC,CAAC;IACpD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,0BAA0B,CAAC;CAC/C;AAsKD,wBAAsB,sBAAsB,CAC1C,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,wBAAwB,CAAC,CAwEnC"}

package/dist/bundle.js

@@ -14,7 +14,7 @@ function errorCode(error) {
 function sha256(bytes) {
     return createHash('sha256').update(bytes).digest('hex');
 }
-async function readBoundedRegularFile(root, relativePath, maximum) {
+async function readBoundedRegularFile(root, relativePath, maximum, allowEmpty = false) {
     const absolutePath = path.join(root, ...relativePath.split('/'));
     let handle;
     try {
@@ -25,14 +25,14 @@ async function readBoundedRegularFile(root, relativePath, maximum) {
         if (!initialStat.isFile()) {
             throw new Error(`Bundle entry is not a regular file: ${relativePath}`);
         }
-        if (initialStat.size < 1 || initialStat.size > maximum) {
+        if (initialStat.size < (allowEmpty ? 0 : 1) || initialStat.size > maximum) {
             throw new Error(`Bundle entry exceeds its byte limit: ${relativePath}`);
         }
         handle = await open(absolutePath, constants.O_RDONLY | constants.O_NOFOLLOW);
         const stat = await handle.stat();
         if (!stat.isFile())
             throw new Error(`Bundle entry is not a regular file: ${relativePath}`);
-        if (stat.size < 1 || stat.size > maximum) {
+        if (stat.size < (allowEmpty ? 0 : 1) || stat.size > maximum) {
             throw new Error(`Bundle entry exceeds its byte limit: ${relativePath}`);
         }
         return await handle.readFile();
@@ -62,6 +62,7 @@ async function verifyExactEntries(root, manifest) {
         DEPLOYMENT_BUNDLE_MANIFEST,
         manifest.deployment.path,
         ...manifest.artifacts.map(artifact => artifact.path),
+        ...(manifest.source?.files.map(file => `${manifest.source.root}/${file.path}`) ?? []),
     ]);
     const expectedDirectoryPaths = expectedDirectories([...expectedFiles]);
     const seenFiles = new Set();
@@ -183,6 +184,14 @@ export async function verifyDeploymentBundle(bundleDirectory) {
         const bytes = await readBoundedRegularFile(root, artifact.path, DEFAULT_PROTOCOL_DEPLOYMENT_BUNDLE_LIMITS.maxArtifactBytes);
         verifyFile(bytes, artifact);
     }
+    const source = preparedManifest.manifest.source;
+    if (source) {
+        for (const file of source.files) {
+            const bundlePath = `${source.root}/${file.path}`;
+            const bytes = await readBoundedRegularFile(root, bundlePath, DEFAULT_PROTOCOL_DEPLOYMENT_BUNDLE_LIMITS.maxSourceFileBytes, true);
+            verifyFile(bytes, { ...file, path: bundlePath });
+        }
+    }
     verifyRuntimeReferences(preparedContract.contract, preparedManifest.manifest.artifacts);
     return Object.freeze({
         directory: root,

package/dist/index.d.ts

@@ -16,7 +16,7 @@ export type { DeploymentControlPlaneLimits } from './control-plane-limits.js';
 export { DEFAULT_DEPLOYMENT_INTAKE_LIMITS, resolveDeploymentIntakeLimits, } from './limits.js';
 export type { DeploymentIntakeLimits } from './limits.js';
 export { createNodeWorkerDeploymentRuntimeFactory, NodeDeploymentRuntimeError, } from './node-runtime-factory.js';
-export type { NodeDeploymentRuntimeErrorCode, NodeDeploymentRuntimeFactoryOptions, } from './node-runtime-factory.js';
+export type { NodeDeploymentRuntimeEnvironment, NodeDeploymentRuntimeEnvironmentResolver, NodeDeploymentRuntimeErrorCode, NodeDeploymentRuntimeFactoryOptions, } from './node-runtime-factory.js';
 export { createDeploymentRuntimeMaterializer, DeploymentRuntimeMaterializationError, } from './runtime-materialization.js';
 export type { DeploymentRuntimeArtifactSnapshot, DeploymentRuntimeMaterializationErrorCode, DeploymentRuntimeMaterializer, DeploymentRuntimeMaterializerOptions, DeploymentRuntimeQueryBinding, DeploymentRuntimeRelease, DeploymentRuntimeReleaseReader, DeploymentRuntimeSnapshot, } from './runtime-materialization.js';
 export { createDeploymentRuntimeSupervisor, DeploymentRuntimeSupervisorError, } from './runtime-supervisor.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/intake.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"intake.d.ts","sourceRoot":"","sources":["../src/intake.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EACV,gBAAgB,EAChB,uBAAuB,EAIxB,MAAM,YAAY,CAAC;AAoSpB,wBAAgB,sBAAsB,CAAC,SAAS,EAC9C,OAAO,EAAE,uBAAuB,CAAC,SAAS,CAAC,GAC1C,gBAAgB,CA6HlB"}
+{"version":3,"file":"intake.d.ts","sourceRoot":"","sources":["../src/intake.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EACV,gBAAgB,EAChB,uBAAuB,EAIxB,MAAM,YAAY,CAAC;AAuSpB,wBAAgB,sBAAsB,CAAC,SAAS,EAC9C,OAAO,EAAE,uBAAuB,CAAC,SAAS,CAAC,GAC1C,gBAAgB,CAiIlB"}

package/dist/intake.js

@@ -88,6 +88,7 @@ function requireReconstructablePaths(manifest) {
     const files = [
         manifest.manifest.deployment.path,
         ...manifest.manifest.artifacts.map(artifact => artifact.path),
+        ...(manifest.manifest.source?.files.map(file => `${manifest.manifest.source.root}/${file.path}`) ?? []),
     ];
     const fileSet = new Set(files);
     if (fileSet.has(DEPLOYMENT_BUNDLE_MANIFEST)) {
@@ -284,6 +285,10 @@ export function createDeploymentIntake(options) {
             const files = [
                 manifest.prepared.manifest.deployment,
                 ...manifest.prepared.manifest.artifacts,
+                ...(manifest.prepared.manifest.source?.files.map(file => ({
+                    ...file,
+                    path: `${manifest.prepared.manifest.source.root}/${file.path}`,
+                })) ?? []),
             ];
             for (let index = 0; index < files.length; index += 1) {
                 await receiveBundleFile(reader, bundleRoot, files[index], index === 0 ? 'application/json' : 'application/octet-stream', index === files.length - 1);

package/dist/node-runtime-factory.d.ts

@@ -1,3 +1,4 @@
+import type { DeploymentRuntimeSnapshot } from './runtime-materialization.js';
 import type { DeploymentRuntimeFactory } from './runtime-supervisor.js';
 export type NodeDeploymentRuntimeErrorCode = 'HQ_NODE_RUNTIME_CONFIGURATION' | 'HQ_NODE_RUNTIME_UNSUPPORTED_ARTIFACT' | 'HQ_NODE_RUNTIME_INVALID_ARTIFACT' | 'HQ_NODE_RUNTIME_START_FAILED' | 'HQ_NODE_RUNTIME_WORKER_EXITED' | 'HQ_NODE_RUNTIME_INVOCATION_FAILED' | 'HQ_NODE_RUNTIME_ABORTED' | 'HQ_NODE_RUNTIME_CLOSED';
 export declare class NodeDeploymentRuntimeError extends Error {
@@ -6,10 +7,20 @@ export declare class NodeDeploymentRuntimeError extends Error {
         readonly cause?: unknown;
     });
 }
+export type NodeDeploymentRuntimeEnvironment = Readonly<Record<string, string>>;
+export type NodeDeploymentRuntimeEnvironmentResolver = (snapshot: DeploymentRuntimeSnapshot, input: {
+    readonly signal?: AbortSignal;
+}) => NodeDeploymentRuntimeEnvironment | Promise<NodeDeploymentRuntimeEnvironment>;
 export interface NodeDeploymentRuntimeFactoryOptions {
     readonly temporaryDirectory?: string;
     /** Worker import deadline from 1 through 300,000 milliseconds. */
     readonly startupTimeoutMs?: number;
+    /**
+     * Resolve an explicit environment for one immutable runtime snapshot.
+     * When configured, this replaces inherited process environment state for
+     * the worker. Omit it to preserve Node's default environment inheritance.
+     */
+    readonly resolveEnvironment?: NodeDeploymentRuntimeEnvironmentResolver;
     readonly onCleanupError?: (error: unknown, directory: string) => void;
 }
 export declare function createNodeWorkerDeploymentRuntimeFactory(options?: NodeDeploymentRuntimeFactoryOptions): DeploymentRuntimeFactory;

package/dist/node-runtime-factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node-runtime-factory.d.ts","sourceRoot":"","sources":["../src/node-runtime-factory.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,wBAAwB,EAGzB,MAAM,yBAAyB,CAAC;AA+CjC,MAAM,MAAM,8BAA8B,GACtC,+BAA+B,GAC/B,sCAAsC,GACtC,kCAAkC,GAClC,8BAA8B,GAC9B,+BAA+B,GAC/B,mCAAmC,GACnC,yBAAyB,GACzB,wBAAwB,CAAC;AAE7B,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,QAAQ,CAAC,IAAI,EAAE,8BAA8B,CAAC;gBAG5C,IAAI,EAAE,8BAA8B,EACpC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAM7C;AAED,MAAM,WAAW,mCAAmC;IAClD,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,kEAAkE;IAClE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;CACvE;AAoSD,wBAAgB,wCAAwC,CACtD,OAAO,GAAE,mCAAwC,GAChD,wBAAwB,CAuB1B"}
+{"version":3,"file":"node-runtime-factory.d.ts","sourceRoot":"","sources":["../src/node-runtime-factory.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,8BAA8B,CAAC;AAC9E,OAAO,KAAK,EACV,wBAAwB,EAGzB,MAAM,yBAAyB,CAAC;AA+CjC,MAAM,MAAM,8BAA8B,GACtC,+BAA+B,GAC/B,sCAAsC,GACtC,kCAAkC,GAClC,8BAA8B,GAC9B,+BAA+B,GAC/B,mCAAmC,GACnC,yBAAyB,GACzB,wBAAwB,CAAC;AAE7B,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,QAAQ,CAAC,IAAI,EAAE,8BAA8B,CAAC;gBAG5C,IAAI,EAAE,8BAA8B,EACpC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAM7C;AAED,MAAM,MAAM,gCAAgC,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAEhF,MAAM,MAAM,wCAAwC,GAAG,CACrD,QAAQ,EAAE,yBAAyB,EACnC,KAAK,EAAE;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,KACrC,gCAAgC,GAAG,OAAO,CAAC,gCAAgC,CAAC,CAAC;AAElF,MAAM,WAAW,mCAAmC;IAClD,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,kEAAkE;IAClE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,wCAAwC,CAAC;IACvE,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;CACvE;AA6XD,wBAAgB,wCAAwC,CACtD,OAAO,GAAE,mCAAwC,GAChD,wBAAwB,CA6B1B"}

package/dist/node-runtime-factory.js

@@ -67,6 +67,63 @@ function startupTimeout(input) {
 function sha256(bytes) {
     return createHash('sha256').update(bytes).digest('hex');
 }
+function invalidEnvironment() {
+    return nodeRuntimeError('HQ_NODE_RUNTIME_START_FAILED', 'The Node deployment runtime environment is invalid.');
+}
+function validateEnvironment(input) {
+    if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+        throw invalidEnvironment();
+    }
+    let keys;
+    try {
+        keys = Reflect.ownKeys(input);
+    }
+    catch {
+        throw invalidEnvironment();
+    }
+    const environment = Object.create(null);
+    for (const key of keys) {
+        if (typeof key !== 'string' || key.length === 0 || key.includes('\0') || key.includes('=')) {
+            throw invalidEnvironment();
+        }
+        let descriptor;
+        try {
+            descriptor = Object.getOwnPropertyDescriptor(input, key);
+        }
+        catch {
+            throw invalidEnvironment();
+        }
+        if (!descriptor?.enumerable
+            || !Object.hasOwn(descriptor, 'value')
+            || typeof descriptor.value !== 'string'
+            || descriptor.value.includes('\0')) {
+            throw invalidEnvironment();
+        }
+        environment[key] = descriptor.value;
+    }
+    return environment;
+}
+async function resolveWorkerEnvironment(resolver, snapshot, signal) {
+    if (!resolver)
+        return undefined;
+    if (signal?.aborted) {
+        throw nodeRuntimeError('HQ_NODE_RUNTIME_ABORTED', 'Node runtime startup was aborted.', signal.reason);
+    }
+    let resolved;
+    try {
+        resolved = await resolver(snapshot, { signal });
+    }
+    catch (error) {
+        if (signal?.aborted) {
+            throw nodeRuntimeError('HQ_NODE_RUNTIME_ABORTED', 'Node runtime startup was aborted.', signal.reason);
+        }
+        throw nodeRuntimeError('HQ_NODE_RUNTIME_START_FAILED', 'The Node deployment runtime environment could not be resolved.', error);
+    }
+    if (signal?.aborted) {
+        throw nodeRuntimeError('HQ_NODE_RUNTIME_ABORTED', 'Node runtime startup was aborted.', signal.reason);
+    }
+    return validateEnvironment(resolved);
+}
 async function ensureTemporaryDirectory(input) {
     const directory = path.resolve(input ?? tmpdir());
     await mkdir(directory, { recursive: true, mode: 0o700 });
@@ -180,7 +237,7 @@ function workerInstance(worker, directory, ready) {
         },
     };
 }
-async function startWorker(snapshot, directory, timeoutMs, signal) {
+async function startWorker(snapshot, directory, timeoutMs, signal, resolveEnvironment) {
     if (signal?.aborted) {
         throw nodeRuntimeError('HQ_NODE_RUNTIME_ABORTED', 'Node runtime startup was aborted.', signal.reason);
     }
@@ -200,9 +257,14 @@ async function startWorker(snapshot, directory, timeoutMs, signal) {
     if (artifacts.length === 0) {
         throw nodeRuntimeError('HQ_NODE_RUNTIME_UNSUPPORTED_ARTIFACT', 'The deployment snapshot contains no Node runtime artifacts.');
     }
+    const environment = await resolveWorkerEnvironment(resolveEnvironment, snapshot, signal);
+    if (signal?.aborted) {
+        throw nodeRuntimeError('HQ_NODE_RUNTIME_ABORTED', 'Node runtime startup was aborted.', signal.reason);
+    }
     const worker = new Worker(WORKER_SOURCE, {
         eval: true,
         workerData: { artifacts },
+        ...(environment === undefined ? {} : { env: environment }),
     });
     let resolveReady;
     let rejectReady;
@@ -257,7 +319,7 @@ export function createNodeWorkerDeploymentRuntimeFactory(options = {}) {
             const directory = await mkdtemp(path.join(root, 'hypequery-node-runtime-'));
             try {
                 await chmod(directory, 0o700);
-                return await startWorker(snapshot, directory, timeoutMs, input.signal);
+                return await startWorker(snapshot, directory, timeoutMs, input.signal, options.resolveEnvironment);
             }
             catch (error) {
                 try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/deployment",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Provider-neutral deployment verification and intake for Hypequery",
   "license": "Apache-2.0",
   "type": "module",
@@ -18,7 +18,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@hypequery/protocol": "0.9.0"
+    "@hypequery/protocol": "0.10.0"
   },
   "devDependencies": {
     "@types/node": "^22.5.0",