@runeditrun/rer 0.0.0-stage → 0.1.0

package/modules/container/build.mjs

@@ -0,0 +1,65 @@
+import { readFile, writeFile, readdir, cp, mkdir, rm } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { createHash } from 'node:crypto';
+import { parseJsonc } from '../../cli/jsonc.mjs';
+import { portabilityPlan } from './portability-schema.mjs';
+import { checkBoundary } from './boundary.mjs';
+const hash = source => createHash('sha256').update(source).digest('hex');
+export async function buildContainer(root, options={}) {
+ const previous=process.cwd();process.chdir(root);
+ try{return await buildImage(root,options);}finally{process.chdir(previous);}
+}
+async function buildImage(root, { output = join(root,'.rer/container/image'), engine, cacheContract, runner, declaration } = {}) {
+ const require = createRequire(join(root,'package.json'));
+ declaration ??= JSON.parse(await readFile(join(root,'deploy.json'),'utf8'));
+ engine ??= declaration.container?.engine ?? 'workerd'; cacheContract ??= declaration.container?.cacheContract; runner ??= declaration.container?.runner;
+ if (!['workerd','node'].includes(engine)) throw new Error('Unsupported container engine');
+ await checkBoundary(root,{engine,cacheContract});
+ const vite = await import(pathToFileURL(require.resolve('vite'))), loaded = await vite.loadConfigFromFile({ command:'build',mode:'production' },undefined,root);
+ if (!loaded) throw new Error('Vite configuration missing');
+ const config = loaded.config;
+ if (engine === 'node') {
+  const plugins = (await Promise.all(config.plugins.flat(Infinity))).filter(plugin => plugin && !plugin.name.startsWith('vite-plugin-cloudflare') && plugin.name !== 'tanstack-start-core:post-build');
+  const bindingShim = resolve(import.meta.dirname,'bindings.mjs');
+  config.plugins = [{ name:'rer-container-bindings', enforce:'pre',
+   resolveId(id) { if (id === 'cloudflare:workers') return bindingShim; },
+   transform(source,id) { if (cacheContract === 'lamp-retained-v1' && id === join(root,'src/server.ts')) return source.replace(/export\s*\{\s*SnapshotCache\s*\}\s*from\s*['"][^'"]+['"];?/,''); },
+  },...plugins];
+  config.ssr = { ...config.ssr,noExternal:true }; config.environments = { ...config.environments,ssr:{ ...config.environments?.ssr,resolve:{ noExternal:true },build:{ ...config.environments?.ssr?.build,rolldownOptions:{ output:{ entryFileNames:'index.mjs' } } } } };
+ }
+ const builder = await vite.createBuilder({ ...config,root,configFile:false }); await builder.buildApp();
+ // Apply the same local-only bundle guard before packaging any container image.
+ await (await import('../../cli/dev-identity.mjs')).refuseDevLayerOutput(root);
+ let workerConfig;
+ if (engine === 'workerd') workerConfig = JSON.parse(await readFile(join(root,'dist/server/wrangler.json'),'utf8'));
+ else workerConfig = parseJsonc(await readFile(join(root,'wrangler.jsonc'),'utf8'));
+ const { unstable_splitSqlQuery:split } = require('wrangler');
+ const migrations = {};
+ for (const db of workerConfig.d1_databases ?? []) {
+  let directory = resolve(root,db.migrations_dir ?? 'migrations');
+  try { await readdir(directory); } catch { directory = resolve(root,'dist/server',db.migrations_dir); }
+  migrations[db.binding] = [];
+  for (const name of (await readdir(directory)).filter(name => name.endsWith('.sql')).sort()) { const sql = await readFile(join(directory,name),'utf8'); migrations[db.binding].push({ name,sql,sha256:hash(sql),statements:split(sql) }); }
+ }
+ const entry = engine === 'workerd' ? 'dist/server/'+workerConfig.main : 'dist/server/index.mjs';
+ await readFile(join(root,entry));
+ if (engine === 'node' && workerConfig.kv_namespaces?.length) throw new Error('Node container does not support KV');
+ for (const secret of declaration.secrets ?? []) if (Object.hasOwn(workerConfig.vars ?? {},secret.binding)) throw new Error('Secret declared as an image variable: '+secret.binding);
+ const manifest = { version:1,engine,entry,cacheContract,runner,config:workerConfig,migrations,portabilityMigrations:await portabilityPlan(split),maxRequestBytes:25*1024*1024 };
+ await rm(output,{recursive:true,force:true}); await mkdir(join(output,'app'),{recursive:true});
+ await cp(join(root,'dist'),join(output,'app/dist'),{recursive:true}); await writeFile(join(output,'app/container.json'),JSON.stringify(manifest,null,2)+'\n');
+ if (runner) {
+  const within = path => { if (typeof path !== 'string' || path.startsWith('/') || path.split('/').some(part => ['..','.',''].includes(part))) throw new Error('Invalid packaged runner path'); return join(root,path); };
+  await readFile(within(runner.entry));
+  for (const path of runner.files) await cp(within(path),join(output,'app/runner',path),{recursive:true,filter:path => !path.includes('/tests/') && !path.endsWith('/synthetic.mjs')});
+ }
+ const base = resolve(import.meta.dirname,'../..');
+ for (const path of ['modules/container','modules/portability','modules/deploy-kit','cli/scheduled.mjs','cli/jsonc.mjs','modules/integrations/core/public-address.ts']) { await mkdir(join(output,'runtime',path,'..'),{recursive:true}); await cp(join(base,path),join(output,'runtime',path),{recursive:true,filter:path => !path.includes('/tests/')}); }
+ const dependencies = engine === 'workerd' ? { miniflare:'5.20260907.0-alpha' } : {};
+ await writeFile(join(output,'runtime/package.json'),JSON.stringify({private:true,type:'module',dependencies}));
+ await writeFile(join(output,'Dockerfile'),`FROM node:26.8.1-bookworm-slim\nRUN apt-get update && apt-get install -y --no-install-recommends util-linux ca-certificates && apt-get clean\nRUN mkdir -p /private /archive\nWORKDIR /runtime\nCOPY runtime/package.json ./package.json\nRUN npm install --omit=dev --no-audit --no-fund\nCOPY runtime/ /runtime/\nCOPY app/ /app/\nENV NODE_ENV=production PORT=8080 WRANGLER_SEND_METRICS=false\nEXPOSE 8080\nVOLUME /data\nENTRYPOINT ["sh", "/runtime/modules/container/entrypoint.sh"]\n`);
+ return { output,manifest };
+}
+if (process.argv[1] === import.meta.filename) { try { const result=await buildContainer(resolve(process.argv[2])); console.log(JSON.stringify({output:result.output,engine:result.manifest.engine})); } catch(cause) { console.error(cause.message); if(cause.failures)console.error(JSON.stringify(cause.failures));process.exitCode=1; } }

package/modules/container/deploy-input.mjs

@@ -0,0 +1,17 @@
+import { open, readFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { refuseLocalModels } from '../deploy-kit/local-only.mjs';
+import { LOCAL_ONLY_KEYS, localOnlyBinding } from '../deploy-kit/owner.mjs';
+export async function deployInputs({root,envFile,localOnlyKeys=[]}) {
+ await refuseLocalModels(root);
+ const declaration=JSON.parse(await readFile(join(root,'deploy.json'),'utf8'));
+ if(localOnlyBinding(declaration,localOnlyKeys))throw new Error('Deploy declaration contains a local-only binding');
+ if(!envFile)throw new Error('Container deploy requires --env-file with private production settings');
+ const handle=await open(resolve(root,envFile),constants.O_RDONLY|constants.O_NOFOLLOW);
+ let encoded;
+ try{const status=await handle.stat();if(!status.isFile()||status.nlink!==1||(status.mode&0o077)!==0||(process.getuid&&status.uid!==process.getuid()))throw new Error('Deploy env file must be an owned private regular file (0600)');encoded=await handle.readFile('utf8');}finally{await handle.close();}
+ const settings={};for(const line of encoded.split(/\r?\n/)){if(!line.trim()||line.trim().startsWith('#'))continue;const match=/^([A-Z][A-Z0-9_]*)=(.*)$/.exec(line);if(!match)throw new Error('Invalid deploy env file');if(Object.hasOwn(settings,match[1]))throw new Error('Repeated deploy env key');settings[match[1]]=match[2].replace(/^"(.*)"$/,'$1');}
+ if([...LOCAL_ONLY_KEYS,...localOnlyKeys].some(key=>Object.hasOwn(settings,key)))throw new Error('Local-only keys are refused for deploy');
+ return{declaration,settings,encoded:Object.entries(settings).map(([key,value])=>key+'='+value).join('\n')+'\n'};
+}

package/modules/container/entrypoint.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+set -eu
+umask 077
+mkdir -p /data
+exec flock --nonblock --no-fork /data/host.lock node /runtime/modules/container/host.mjs "$@"

package/modules/container/host.mjs

@@ -0,0 +1,43 @@
+import { createServer } from 'node:http';
+import { readFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { recordVolumeOwner } from './lock.mjs';
+import { incoming, outgoing } from './ingress.mjs';
+import { parseCron, cronMatches } from '../../cli/scheduled.mjs';
+import { superviseRunner } from './runner.mjs';
+export async function startHost({ root = '/app', data = '/data', settings = process.env, port = Number(process.env.PORT ?? 8080), edge, engineVersion = process.version, automaticTicks=true, runnerEnabled=true } = {}) {
+ await mkdir(data, { recursive:true });
+ const manifest = JSON.parse(await readFile(join(root, 'container.json'), 'utf8'));
+ const release = await recordVolumeOwner(data);
+ let engine, server, timer, idleTimer, runner, closing, lastMinute = -1, lastRequest=Date.now();
+ try {
+  const create = manifest.engine === 'node' ? (await import('./node-engine.mjs')).nodeEngine : (await import('./worker-engine.mjs')).workerEngine;
+  engine = await create({ root,data,manifest,settings,edge });
+  const schedules = (manifest.config.triggers?.crons ?? []).map(cron => [cron,parseCron(cron)]);
+  const tick = async time => { for (const [cron, expression] of schedules) if (cronMatches(expression, new Date(time))) await engine.scheduled({ cron,scheduledTime:time }); await engine.drain(); };
+  server = createServer(async (req, res) => {
+   try {
+    lastRequest=Date.now();
+    const request = await incoming(req, { trustedProxy:settings.TRUSTED_PROXY, maxRequestBytes:manifest.maxRequestBytes });
+    let response = await engine.fetch(request);
+    if (new URL(request.url).pathname === '/health' && response.ok) {
+     const body = await response.json(); const deadJobs = engine.dead();
+     response = Response.json({ ...body, platform:'container', deployment:{ ...body.deployment, platform:'container', versionId:settings.RER_IMAGE_DIGEST ?? null }, container:{ engine:manifest.engine,engineVersion,deadJobs,runner:manifest.runner ? (runner?.running() ? 'running' : 'stopped') : null } }, { status:deadJobs || (manifest.runner && runnerEnabled && !runner?.running()) ? 503 : response.status,headers:response.headers });
+    }
+    outgoing(response, res);
+   } catch (cause) { res.statusCode = cause.status ?? 500; res.end('Container request failed'); console.error('Container request failed:', cause.name); }
+  });
+  await new Promise((resolve, reject) => { server.once('error', reject); server.listen(port,'0.0.0.0',resolve); });
+  let ticking=false;
+  if(automaticTicks){timer = setInterval(async () => { if(ticking)return;ticking=true;const minute = Math.floor(Date.now()/60000); try { if (minute !== lastMinute) { lastMinute = minute; await tick(minute * 60000); } else await engine.drain(); } catch { console.error('Container scheduled event failed'); }finally{ticking=false;} },1000); timer.unref();}
+  const close = () => closing ??= (async () => { clearInterval(timer); clearInterval(idleTimer); await runner?.close(); await new Promise(resolve => server.close(resolve)); await engine.close(); await release(); })();
+  const idle=Number(settings.RER_CONTAINER_IDLE_SECONDS);if(Number.isFinite(idle)&&idle>0){idleTimer=setInterval(()=>{if(Date.now()-lastRequest>=idle*1000)void close();},Math.min(1000,idle*1000));idleTimer.unref();}
+  if(runnerEnabled)runner=superviseRunner({root,manifest,settings,failed(){console.error('Required container runner stopped');void close().finally(()=>{process.exitCode=1;});}});
+  return { engine,manifest,server,tick,close };
+ } catch (cause) { clearInterval(timer); clearInterval(idleTimer); await runner?.close(); server?.close(); await engine?.close(); await release(); throw cause; }
+}
+if (process.argv[1] === import.meta.filename) {
+ let host;
+ try { host = await startHost(); console.log('RER_CONTAINER_READY'); } catch (cause) { console.error('Container startup failed:', cause.message?.match(/^[a-z-]+$/)?.[0] ?? cause.name); process.exitCode=1; }
+ if (host) for (const signal of ['SIGINT','SIGTERM']) process.once(signal,async () => { await host.close(); process.exit(0); });
+}

package/modules/container/ingress.mjs

@@ -0,0 +1,23 @@
+import { Readable } from 'node:stream';
+import { lookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+export async function incoming(req, { trustedProxy, maxRequestBytes = 25 * 1024 * 1024 } = {}) {
+ const headers = new Headers(); for (const [name, value] of Object.entries(req.headers)) if (value !== undefined) headers.set(name, Array.isArray(value) ? value.join(',') : value);
+ const peer = req.socket.remoteAddress?.replace('::ffff:', '') ?? '';
+ const trusted = trustedProxy && (isIP(trustedProxy) ? peer===trustedProxy : (await lookup(trustedProxy,{all:true})).some(item=>item.address.replace('::ffff:','')===peer));
+ let host = req.headers.host, proto = 'http', address = peer;
+ if (trusted) { host = req.headers['x-forwarded-host'] ?? host; proto = req.headers['x-forwarded-proto'] ?? proto; address = req.headers['x-forwarded-for']?.split(',').at(-1)?.trim() ?? peer; }
+ for (const name of ['cf-connecting-ip','x-forwarded-host','x-forwarded-proto','x-forwarded-for','forwarded','x-rer-original-url']) headers.delete(name);
+ if (!['http', 'https'].includes(proto) || typeof host !== 'string' || !/^(?:[a-zA-Z0-9.-]+|\[[0-9a-fA-F:]+\])(?::[0-9]+)?$/.test(host)) throw new Error('Invalid ingress origin');
+ headers.set('cf-connecting-ip', address); headers.set('host', host);
+ const url = `${proto}://${host}${req.url}`;
+ const chunks = []; let size = 0;
+ for await (const chunk of req) { size += chunk.length; if (size > maxRequestBytes) { const error = new Error('Request too large'); error.status = 413; throw error; } chunks.push(chunk); }
+ return new Request(url, { method: req.method, headers, ...(!['GET','HEAD'].includes(req.method) ? { body: Buffer.concat(chunks) } : {}) });
+}
+export function outgoing(response, res) {
+ res.statusCode = response.status;
+ for (const [name, value] of response.headers) if (!['set-cookie','content-length','transfer-encoding'].includes(name)) res.setHeader(name, value);
+ const cookies = response.headers.getSetCookie(); if (cookies.length) res.setHeader('set-cookie', cookies);
+ if (response.body) { const stream = Readable.fromWeb(response.body); res.once('close', () => stream.destroy()); stream.once('error', () => res.destroy()); stream.pipe(res); } else res.end();
+}

package/modules/container/lock.mjs

@@ -0,0 +1,11 @@
+import { open } from 'node:fs/promises';
+import { join } from 'node:path';
+// entrypoint.sh holds a kernel flock on this inode for the entire process lifetime.
+// It works across container PID namespaces and releases automatically on SIGKILL.
+// Never unlink the lock inode: a new inode would permit a second live holder.
+export async function recordVolumeOwner(directory) {
+ const file = await open(join(directory, 'host.lock'), 'r+', 0o600);
+ const write = async () => { const bytes = Buffer.from(JSON.stringify({ pid: process.pid, heartbeat: new Date().toISOString() })); await file.truncate(0); await file.write(bytes, 0, bytes.length, 0); await file.sync(); };
+ await write(); const timer = setInterval(() => void write().catch(() => { process.exitCode = 1; }), 10000); timer.unref();
+ return async () => { clearInterval(timer); await file.close(); };
+}

package/modules/container/migrations.mjs

@@ -0,0 +1,16 @@
+import { validateMigrations } from '../deploy-kit/migrations.mjs';
+export async function migrate(db, migrations, { ledger = '_rer_deploy_migrations' } = {}) {
+ if (!['_rer_deploy_migrations', '_rer_portability_migrations'].includes(ledger)) throw new Error('Invalid migration ledger');
+ validateMigrations(migrations);
+ await db.prepare(`CREATE TABLE IF NOT EXISTS ${ledger}(name TEXT PRIMARY KEY,sha256 TEXT NOT NULL,state TEXT NOT NULL CHECK(state IN ('applying','applied')))`).run();
+ const history = (await db.prepare(`SELECT name,sha256,state FROM ${ledger} ORDER BY name`).all()).results;
+ if (history.some((row, i) => row.name !== migrations[i]?.name || row.sha256 !== migrations[i]?.sha256 || row.state !== 'applied')) throw new Error('changed-or-uncertain-migration-history');
+ const legacy = await db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='d1_migrations'").first();
+ if (ledger === '_rer_deploy_migrations' && legacy && (await db.prepare('SELECT name FROM d1_migrations ORDER BY id').all()).results.some(row => !history.some(prior => prior.name === row.name))) throw new Error('legacy-migration-history-needs-reviewed-hash-adoption');
+ for (const migration of migrations.slice(history.length)) {
+  await db.prepare(`INSERT INTO ${ledger} VALUES(?,?,'applying')`).bind(migration.name, migration.sha256).run();
+  // A claim commits separately. Application and completion share one transaction.
+  await db.batch([...migration.statements.map(sql => db.prepare(sql)), db.prepare(`UPDATE ${ledger} SET state='applied' WHERE name=? AND sha256=? AND state='applying'`).bind(migration.name, migration.sha256)]);
+ }
+ return { applied: migrations.length, pending: 0 };
+}

package/modules/container/node-engine.mjs

@@ -0,0 +1,39 @@
+import { DatabaseSync } from 'node:sqlite';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { D1 } from './adapters/d1.mjs';
+import { Jobs } from './adapters/jobs.mjs';
+import { Objects } from './adapters/objects.mjs';
+import { retainedCache } from './adapters/retained.mjs';
+import { publicFetch } from './adapters/egress.mjs';
+import { assets } from './assets.mjs';
+import { ensurePortabilitySchema } from './portability-schema.mjs';
+import { migrate } from './migrations.mjs';
+export async function nodeEngine({ root, data, manifest, settings, edge }) {
+ const platform = new DatabaseSync(join(data, 'platform.sqlite')); platform.exec('PRAGMA journal_mode=WAL; PRAGMA foreign_keys=ON');
+ const env = { ...manifest.config.vars, ...settings, ASSETS: assets(join(root, 'dist/client')) }, databases = {}, queues = [];
+ for (const [binding, plan] of Object.entries(manifest.migrations)) { const db = new D1(join(data, binding + '.sqlite')); databases[binding] = db; env[binding] = db; await migrate(db, plan); await ensurePortabilitySchema(db, manifest.portabilityMigrations); }
+ const objects = {};
+ for (const bucket of manifest.config.r2_buckets ?? []) { const store = new Objects(platform, join(data, 'objects'), bucket.binding); objects[bucket.binding] = store; env[bucket.binding] = store; }
+ await Object.values(objects)[0]?.recover();
+ for (const producer of manifest.config.queues?.producers ?? []) { const consumer = manifest.config.queues.consumers.find(item => item.queue === producer.queue); const jobs = new Jobs(platform, producer.queue, { maxRetries: consumer?.max_retries, batchSize: consumer?.max_batch_size }); env[producer.binding] = jobs; queues.push(jobs); }
+ if (manifest.config.durable_objects?.bindings?.length) {
+  for (const binding of manifest.config.durable_objects.bindings) { if (manifest.cacheContract !== 'lamp-retained-v1' || binding.class_name !== 'SnapshotCache') throw new Error('Unsupported Node binding'); env[binding.name] = retainedCache(platform); }
+ }
+ globalThis[Symbol.for('rer.container.bindings')] = env;
+ const previousFetch = globalThis.fetch; globalThis.fetch = edge ? (input, init) => edge(new Request(input, init), publicFetch) : publicFetch;
+ // Lamp uses its persistent retained contract; the optional Cache API is deliberately unsupported.
+ globalThis.caches = { open: async () => { throw new Error('Cache API unavailable on container Node'); } };
+ const app = (await import(pathToFileURL(join(root, manifest.entry)))).default;
+ const pending = new Set(), execution = { waitUntil(promise) { pending.add(promise); promise.catch(() => console.error('Background effect failed')).finally(() => pending.delete(promise)); } };
+ return { env, databases, objects, app, execution,
+  async fetch(request) {
+   if(['GET','HEAD'].includes(request.method)&&!manifest.config.assets?.run_worker_first){const response=await env.ASSETS.fetch(request);if(response.status!==404)return response;}
+   return app.fetch(request,env,execution);
+  },
+  scheduled: event => app.scheduled?.(event, env, execution),
+  async drain() { if (app.queue) for (const jobs of queues) await jobs.drain(app.queue.bind(app), env, execution); },
+  dead: () => queues.reduce((sum, jobs) => sum + jobs.dead(), 0),
+  async close() { await Promise.allSettled([...pending]); await Promise.all(Object.values(databases).map(db => db.close())); platform.close(); globalThis.fetch = previousFetch; },
+ };
+}

package/modules/container/portability-schema.mjs

@@ -0,0 +1,14 @@
+import { readFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { migrate } from './migrations.mjs';
+export async function portabilityPlan(split) {
+ const sql = await readFile(new URL('../portability/schema/portability.sql', import.meta.url), 'utf8');
+ return [{ name:'0001_portability.sql', sql, sha256:createHash('sha256').update(sql).digest('hex'), statements:split(sql) }];
+}
+// Existing product-owned bookkeeping remains under its original migrations.
+// Independently installed bookkeeping cannot interleave later product migrations.
+export async function ensurePortabilitySchema(db, plan) {
+ const owned = await db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='_rer_portability_migrations'").first();
+ if (!owned && await db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='rer_portability_state'").first()) return;
+ await migrate(db, plan, { ledger:'_rer_portability_migrations' });
+}

package/modules/container/remote/deploy.py

@@ -0,0 +1,76 @@
+import sys
+
+
+def deploy():
+    payload = json.load(sys.stdin)
+    plan = payload['plan']
+    install, lock, path, chain = open_install(plan)
+    stage = generation_fd = None
+    previous, pending = {}, {}
+    try:
+        # Retain cleanup identities before Docker/other asynchronous work can
+        # give another process an opportunity to substitute private paths.
+        for entry in os.listdir(install):
+            if re.fullmatch(r'(generation|stage)-[0-9a-f]{32}', entry):
+                previous[entry] = retain_generation(install, entry)
+            elif re.fullmatch(r'current-[0-9a-f]{32}', entry):
+                pending[entry] = file_info(install, entry)
+                if pending[entry] is None:
+                    refuse('Host deployment path changed')
+        manifest = retain_file(install, 'current.json')
+        def validate_previous():
+            for entry, (fd, entries) in previous.items():
+                validate_generation_entries(install, entry, fd, entries)
+            for entry, created in pending.items():
+                same_inode(created, file_info(install, entry))
+            same_file(install, 'current.json', manifest)
+        owned, containers = inventory(plan)
+        admit_ports(plan, owned, containers)
+        if payload.get('phase') == 'check':
+            print('{}')
+            return
+        stage, generation, generation_fd, records = stage_files(install, payload['files'])
+        caddy = prepare_resources(plan, owned)
+        # Recheck destinations and all resource ownership immediately before
+        # committing a complete generation and before the first shutdown.
+        inventory(plan)
+        validate_install(chain, lock, plan)
+        validate_previous()
+        validate_generation(install, stage, generation_fd, records)
+        publish_generation(install, stage, generation)
+        stage = generation
+        manifest = commit_manifest(install, generation, manifest)
+        stage = None
+        def validate():
+            validate_install(chain, lock, plan)
+            validate_previous()
+            validate_generation(install, generation, generation_fd, records)
+        replace_containers(plan, validate, payload['files'], caddy)
+        validate()
+        for entry, (fd, entries) in previous.items():
+            remove_generation(install, entry, fd, entries)
+        for entry, created in pending.items():
+            same_inode(created, file_info(install, entry))
+            os.unlink(entry, dir_fd=install)
+        print(json.dumps({'installation': path, 'generation': generation}))
+    finally:
+        try:
+            if stage:
+                remove_generation(install, stage, generation_fd, {filename: created for filename, (_, created) in records.items()})
+        finally:
+            if generation_fd is not None:
+                os.close(generation_fd)
+            for fd, _ in previous.values():
+                os.close(fd)
+            for _, fd, _ in reversed(chain):
+                os.close(fd)
+            os.close(lock)
+
+
+try:
+    deploy()
+except BaseException as error:
+    # No exceptions from parsers or subprocesses may echo private inputs.
+    message = str(error) if isinstance(error, RuntimeError) else 'Host deployment refused: unsafe path or failed operation'
+    print(message, file=sys.stderr)
+    sys.exit(1)

package/modules/container/remote/files.py

@@ -0,0 +1,275 @@
+"""Private dirfd custody, including verification of the live pathname chain."""
+import os, stat, json, pwd, uuid, fcntl, re
+
+
+def refuse(message):
+    raise RuntimeError(message)
+
+
+def metadata(info, directory=False, ancestor=False):
+    kind = stat.S_ISDIR if directory else stat.S_ISREG
+    owners = {0, os.getuid()} if ancestor else {os.getuid()}
+    mask = 0o022 if ancestor else 0o077
+    if not kind(info.st_mode) or info.st_uid not in owners or info.st_mode & mask or (not directory and info.st_nlink != 1):
+        refuse('Unsafe host path ownership, permissions or type')
+    return info
+
+
+def checked(fd, directory=False, ancestor=False):
+    return metadata(os.fstat(fd), directory, ancestor)
+
+
+def same_inode(left, right):
+    if right is None or (left.st_dev, left.st_ino) != (right.st_dev, right.st_ino):
+        refuse('Host deployment path changed')
+
+
+def directory(parent, name, create=False, ancestor=False):
+    if create:
+        try:
+            os.mkdir(name, 0o700, dir_fd=parent)
+        except FileExistsError:
+            pass
+    fd = os.open(name, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=parent)
+    try:
+        checked(fd, True, ancestor)
+        return fd
+    except BaseException:
+        os.close(fd)
+        raise
+
+
+def file_info(parent, name):
+    try:
+        metadata(os.stat(name, dir_fd=parent, follow_symlinks=False))
+        fd = os.open(name, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=parent)
+    except FileNotFoundError:
+        return None
+    try:
+        return checked(fd)
+    finally:
+        os.close(fd)
+
+
+def read_json(parent, name):
+    metadata(os.stat(name, dir_fd=parent, follow_symlinks=False))
+    fd = os.open(name, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=parent)
+    try:
+        checked(fd)
+        with os.fdopen(os.dup(fd)) as stream:
+            return json.load(stream)
+    finally:
+        os.close(fd)
+
+
+def exclusive(parent, name, content):
+    fd = os.open(name, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600, dir_fd=parent)
+    try:
+        checked(fd)
+        with os.fdopen(os.dup(fd), 'wb') as stream:
+            stream.write(content.encode())
+            stream.flush()
+            os.fsync(stream.fileno())
+        return checked(fd)
+    finally:
+        os.close(fd)
+
+
+def retain_file(parent, name):
+    # Identity plus exact bytes: a same-UID file transplanted from another
+    # installation passes every ownership and permission check.
+    try:
+        metadata(os.stat(name, dir_fd=parent, follow_symlinks=False))
+        fd = os.open(name, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=parent)
+    except FileNotFoundError:
+        return None
+    try:
+        info = checked(fd)
+        with os.fdopen(os.dup(fd), 'rb') as stream:
+            return info, stream.read(65537)
+    finally:
+        os.close(fd)
+
+
+def same_file(parent, name, retained):
+    current = retain_file(parent, name)
+    if retained is None or current is None:
+        if retained is not current:
+            refuse('Host deployment path changed')
+        return
+    same_inode(retained[0], current[0])
+    if current[1] != retained[1]:
+        refuse('Host deployment file changed')
+
+
+def open_install(plan):
+    # Do not resolve symlinks before checking them. System ancestors may belong
+    # to root; the account home and private deployment tree must belong to uid.
+    home = pwd.getpwuid(os.getuid()).pw_dir
+    if not home.startswith('/') or any(part in ('.', '..') for part in home.split('/')):
+        refuse('Unsafe account home')
+    fd = os.open('/', os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+    checked(fd, True, True)
+    chain = [('/', fd, True)]
+    for part in filter(None, home.split('/')):
+        nxt = directory(fd, part, ancestor=True)
+        chain.append((part, nxt, True))
+        fd = nxt
+    info = os.fstat(fd)
+    if info.st_uid != os.getuid():
+        refuse('Account home is not owned by login user')
+    base = directory(fd, '.rer-host', create=True)
+    chain.append(('.rer-host', base, False))
+    # One host-account lock also serializes creation and binding admission for
+    # cooperating installs. The pathname chain is checked independently of it.
+    file_info(base, 'deploy.lock')
+    lock = os.open('deploy.lock', os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW | os.O_NONBLOCK, 0o600, dir_fd=base)
+    checked(lock)
+    fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+    created = False
+    try:
+        os.mkdir(plan['name'], 0o700, dir_fd=base)
+        created = True
+    except FileExistsError:
+        pass
+    install = directory(base, plan['name'])
+    chain.append((plan['name'], install, False))
+    if created:
+        exclusive(install, 'owner.json', json.dumps(plan['labels']))
+    if read_json(install, 'owner.json') != plan['labels']:
+        refuse('Installation ownership mismatch')
+    validate_install(chain, lock, plan)
+    return install, lock, home + '/.rer-host/' + plan['name'], chain
+
+
+def validate_install(chain, lock, plan):
+    # A retained dirfd remains usable after rename. Check each original edge
+    # from / as well, so it cannot silently become a detached installation.
+    parent = None
+    for name, fd, ancestor in chain:
+        info = checked(fd, True, ancestor)
+        if parent is not None:
+            linked = metadata(os.stat(name, dir_fd=parent, follow_symlinks=False), True, ancestor)
+            same_inode(info, linked)
+        parent = fd
+    if os.fstat(chain[-3][1]).st_uid != os.getuid():
+        refuse('Account home is not owned by login user')
+    same_inode(checked(lock), file_info(chain[-2][1], 'deploy.lock'))
+    install = chain[-1][1]
+    if read_json(install, 'owner.json') != plan['labels']:
+        refuse('Installation ownership mismatch')
+    validate_tree(install)
+
+
+def validate_tree(install):
+    checked(install, True)
+    for entry in os.listdir(install):
+        if entry in ('owner.json', 'current.json'):
+            file_info(install, entry)
+        elif re.fullmatch(r'current-[0-9a-f]{32}', entry):
+            file_info(install, entry)
+        elif re.fullmatch(r'(generation|stage)-[0-9a-f]{32}', entry):
+            child = directory(install, entry)
+            try:
+                for name in os.listdir(child):
+                    if name not in ('settings.env', 'compose.yaml', 'Caddyfile'):
+                        refuse('Unexpected deployment file')
+                    file_info(child, name)
+            finally:
+                os.close(child)
+        else:
+            refuse('Unexpected installation path')
+
+
+def stage_files(install, files):
+    token = uuid.uuid4().hex
+    stage = 'stage-' + token
+    os.mkdir(stage, 0o700, dir_fd=install)
+    fd = directory(install, stage)
+    try:
+        records = {}
+        for name, contents in files.items():
+            records[name] = (contents, exclusive(fd, name, contents))
+        os.fsync(fd)
+        return stage, 'generation-' + token, fd, records
+    except BaseException:
+        os.close(fd)
+        raise
+
+
+def validate_generation(install, name, fd, records):
+    validate_generation_entries(install, name, fd, {filename: created for filename, (_, created) in records.items()})
+    for filename, (contents, created) in records.items():
+        file = os.open(filename, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=fd)
+        try:
+            same_inode(created, checked(file))
+            with os.fdopen(os.dup(file), 'rb') as stream:
+                if stream.read(len(contents.encode()) + 1) != contents.encode():
+                    refuse('Host deployment file changed')
+        finally:
+            os.close(file)
+
+
+def validate_generation_entries(install, name, fd, entries):
+    same_inode(checked(fd, True), metadata(os.stat(name, dir_fd=install, follow_symlinks=False), True))
+    if set(os.listdir(fd)) != set(entries):
+        refuse('Unexpected deployment file')
+    for filename, created in entries.items():
+        same_inode(created, file_info(fd, filename))
+
+
+def retain_generation(install, name):
+    fd = directory(install, name)
+    try:
+        entries = {}
+        for filename in os.listdir(fd):
+            if filename not in ('settings.env', 'compose.yaml', 'Caddyfile'):
+                refuse('Unexpected deployment file')
+            info = file_info(fd, filename)
+            if info is None:
+                refuse('Host deployment path changed')
+            entries[filename] = info
+        validate_generation_entries(install, name, fd, entries)
+        return fd, entries
+    except BaseException:
+        os.close(fd)
+        raise
+
+
+def publish_generation(install, stage, generation):
+    validate_tree(install)
+    os.rename(stage, generation, src_dir_fd=install, dst_dir_fd=install)
+
+
+def commit_manifest(install, generation, current):
+    # A single atomic commit points to a complete generation; interrupted
+    # transfers cannot make an existing installation run partial configuration.
+    # Only the manifest retained before asynchronous work may be replaced.
+    content = json.dumps({'generation': generation})
+    pending = 'current-' + uuid.uuid4().hex
+    committed = (exclusive(install, pending, content), content.encode())
+    try:
+        same_file(install, pending, committed)
+        same_file(install, 'current.json', current)
+        os.replace(pending, 'current.json', src_dir_fd=install, dst_dir_fd=install)
+        os.fsync(install)
+        same_file(install, 'current.json', committed)
+        return committed
+    finally:
+        remaining = file_info(install, pending)
+        if remaining is not None:
+            same_inode(committed[0], remaining)
+            os.unlink(pending, dir_fd=install)
+
+
+def remove_generation(install, name, fd, entries):
+    # A private path can still have been replaced by the same login UID.
+    # Validate the whole retained generation before removing any member, then
+    # require the captured identity again immediately before each deletion.
+    validate_generation_entries(install, name, fd, entries)
+    for entry, created in entries.items():
+        same_inode(checked(fd, True), metadata(os.stat(name, dir_fd=install, follow_symlinks=False), True))
+        same_inode(created, file_info(fd, entry))
+        os.unlink(entry, dir_fd=fd)
+    same_inode(checked(fd, True), metadata(os.stat(name, dir_fd=install, follow_symlinks=False), True))
+    os.rmdir(name, dir_fd=install)