@bongos/core 1.25.16 → 1.25.17

package/scripts/bongos/provision-render-sandbox.js

@@ -0,0 +1,171 @@
+'use strict';
+// provision-render-sandbox.js — the project's SANDBOX on Render: set it up beside the app,
+// and remove it at teardown (task 1005289; ADR 0406, ADR 0327).
+//
+// WHY. Every project whose app runs on Render gets a second, free app from the same
+// repository that follows `main` on every merge, so finished work reaches a test copy
+// first and the live site moves only when a person promotes (ADR 0406 §2). This file is
+// the runner half; the web tier queues it (modules/provisioning/render-sandbox.js) and the
+// standup leg calls it after the app (provision-render.js), with the same borrowed key.
+//
+// THREE STAGES, kept apart so one failing never takes the others down:
+//   1. BUILD — the app's own build settings: what the owner gave (new app), or read off
+//      their existing service (a linked one).
+//   2. DATABASE — never Render's free database (it expires, one per workspace: ADR 0406
+//      §4). When the app has a PAID database we created, a second database is made INSIDE
+//      that server with plain SQL (Render's docs: "Adding multiple databases to a single
+//      instance" — there is no API call for it). No app database → no sandbox database.
+//      A failure here leaves the sandbox running with NO database and says why; it never
+//      falls back to buying one — that is the owner's call (ADR 0406 §6 choice 1).
+//   3. SERVICE — a free web service named `<slug>-sandbox`, auto-deploying from `main`,
+//      with BONGOS_SANDBOX=1. Found by name first, so a re-run never makes a second one.
+//
+// The live service is not touched here: switching it to manual deploys belongs with the
+// promote button that replaces them (task 1005290).
+//
+// TEARDOWN removes the sandbox service and the sandbox database only — never the live app
+// or its data (ADR 0406 §7). It needs the owner's key; without one the sandbox is
+// forgotten and the owner is told exactly what to delete.
+
+const payload = require('./render-payload.js');
+const { parseTargetRef } = require('./provision-repo-auth.js');
+
+async function recordSandbox(db, instId, patch) {
+  await db.query(
+    `UPDATE provisioning_instances
+        SET app_host = COALESCE(app_host, '{}'::jsonb)
+                       || jsonb_build_object('sandbox', COALESCE(app_host->'sandbox', '{}'::jsonb) || $2::jsonb)
+      WHERE id = $1`,
+    [instId, JSON.stringify({ ...patch, updatedAt: new Date().toISOString() })]);
+}
+
+// Run SQL against the app's database SERVER from the runner. Uses the server's external
+// address (the runner is outside Render's network). Injected in tests: no real database.
+async function defaultSqlRunner(connectionString, statements) {
+  const { Client } = require('pg');
+  const c = new Client({ connectionString, ssl: { rejectUnauthorized: true }, connectionTimeoutMillis: 15000 });
+  await c.connect();
+  try {
+    const out = [];
+    for (const s of statements) out.push(await c.query(s.text, s.values || []));
+    return out;
+  } finally { await c.end().catch(() => {}); }
+}
+
+// The same connection string pointed at another database on the same server.
+function withDatabase(connectionString, dbName) {
+  const u = new URL(connectionString);
+  u.pathname = `/${dbName}`;
+  return u.toString();
+}
+
+// Stage 2. Returns { state: 'ready', name, url } | { state: 'none' | 'failed', note }.
+async function sandboxDatabase(api, inst, host, deps) {
+  if (!host.postgresId) {
+    return { state: 'none', note: host.mode === 'adopt'
+      ? 'Bongos did not create your app’s database, so the sandbox has none. It runs your app without data.'
+      : 'Your app has no database, so its sandbox has none either.' };
+  }
+  try {
+    const pg = await api.getPostgres(host.postgresId);
+    if (pg.plan === 'free') return { state: 'none', note: 'Your app’s database is on Render’s free plan, which cannot hold a sandbox database, so the sandbox has none.' };
+    const conn = await api.postgresConnectionInfo(pg.id);
+    const ext = conn && conn.externalConnectionString;
+    const int = conn && conn.internalConnectionString;
+    if (!ext || !int) throw new Error('Render gave no connection address for your database');
+    const name = payload.sandboxDbName(inst);
+    const run = deps.sqlRunner || defaultSqlRunner;
+    const [exists] = await run(ext, [{ text: 'SELECT 1 FROM pg_database WHERE datname = $1', values: [name] }]);
+    if (!(exists && exists.rows && exists.rows.length)) await run(ext, [{ text: `CREATE DATABASE "${name}"` }]);
+    return { state: 'ready', name, url: withDatabase(int, name) };
+  } catch (e) {
+    return { state: 'failed', note: `The sandbox’s own database could not be made, so the sandbox runs with no data: ${String((e && e.message) || e).split('\n')[0].slice(0, 200)}` };
+  }
+}
+
+// Stages 1-3. Never throws: a sandbox failure is recorded on the sandbox and never fails
+// the app it sits beside. Returns { ok, error? }.
+async function standupSandbox(api, inst, host, deps) {
+  const { db, log } = deps;
+  try {
+    const repo = parseTargetRef(inst.target_ref);
+    if (!repo) throw new Error('the project has no GitHub repository for the sandbox to build from');
+    // 1. build settings
+    let build, region = host.region || payload.DEFAULTS.region;
+    if (host.mode === 'adopt') {
+      const live = await api.getService(host.serviceId);
+      build = payload.buildFromService(live);
+      if (!build) throw new Error('Render did not say how your linked service is built, so the sandbox could not copy it');
+      region = (live.serviceDetails && live.serviceDetails.region) || region;
+    } else {
+      build = payload.buildFor(host);
+    }
+    await recordSandbox(db, inst.id, { state: 'creating', error: null });
+    // 2. database — its own stage; its failure is the sandbox's note, not its end
+    const sb = host.sandbox || {};
+    const dbStage = await sandboxDatabase(api, inst, host, deps);
+    await recordSandbox(db, inst.id, { database: dbStage.state, dbName: dbStage.name || null, dbNote: dbStage.note || null });
+    log(`  [render] sandbox database: ${dbStage.state}${dbStage.name ? ` (${dbStage.name})` : ''}`);
+    // 3. the free service, found before created
+    const name = payload.resourceName(inst, 'sandbox');
+    let svc = sb.serviceId ? await api.getService(sb.serviceId).catch(() => null) : null;
+    if (!svc) svc = await api.findServiceByName(name);
+    if (!svc) {
+      const created = await api.createService(payload.sandboxServicePayload(inst, {
+        ownerId: api.ownerId, repoUrl: `https://github.com/${repo.owner}/${repo.name}`, region, build,
+        dbUrl: dbStage.state === 'ready' ? dbStage.url : null,
+      }));
+      svc = created.service;
+      log(`  [render] created sandbox service ${svc.id} (free, follows main)`);
+    }
+    const url = (svc.serviceDetails && svc.serviceDetails.url) || null;
+    await recordSandbox(db, inst.id, { state: 'deploying', serviceId: svc.id, serviceUrl: url, error: null });
+    return { ok: true };
+  } catch (e) {
+    const error = `The sandbox could not be set up: ${String((e && e.message) || e).split('\n')[0].slice(0, 240)}`;
+    await recordSandbox(db, inst.id, { state: 'failed', error }).catch(() => {});
+    log(`  ✖ [render] ${inst.slug} sandbox: ${error}`);
+    return { ok: false, error };
+  }
+}
+
+// Teardown's half for the sandbox. `api` is a Render client built from the key the owner
+// lent with the teardown, or null when they lent none.
+async function removeSandbox(inst, { db, log, apply, sqlRunner }, api) {
+  const host = inst.app_host || {};
+  const sb = host.sandbox;
+  if (host.platform !== 'render' || !sb || (!sb.serviceId && !sb.dbName)) return { removed: false, reason: 'none' };
+  if (!api) {
+    const what = [sb.serviceId && `the service ${payload.resourceName(inst, 'sandbox')}`, sb.dbName && `the database ${sb.dbName} inside your app’s database`].filter(Boolean).join(' and ');
+    log(`  [render] sandbox left on Render (no key lent with the teardown): ${what}`);
+    if (apply) await recordSandbox(db, inst.id, { state: 'left', error: `No Render key came with the teardown, so the sandbox is still on your Render account: remove ${what} there.` });
+    return { removed: false, reason: 'no_key' };
+  }
+  const notes = [];
+  let dbGone = !sb.dbName;
+  if (sb.serviceId) {
+    if (apply) await api.deleteSandboxService(sb.serviceId);
+    notes.push(`service ${sb.serviceId}`);
+  }
+  if (sb.dbName && host.postgresId && payload.SANDBOX_DB_RE.test(sb.dbName)) {
+    try {
+      const conn = await api.postgresConnectionInfo(host.postgresId);
+      if (apply && conn && conn.externalConnectionString) {
+        await (sqlRunner || defaultSqlRunner)(conn.externalConnectionString, [{ text: `DROP DATABASE IF EXISTS "${sb.dbName}" WITH (FORCE)` }]);
+      }
+      notes.push(`database ${sb.dbName}`);
+      dbGone = true;
+    } catch (e) {
+      log(`  (sandbox database ${sb.dbName} not dropped: ${e && e.message})`);
+    }
+  }
+  log(`  [render] ${apply ? 'removed' : 'would remove'} the sandbox (${notes.join(' and ')}); the live app is untouched`);
+  if (apply) {
+    await recordSandbox(db, inst.id, dbGone
+      ? { state: 'removed', serviceId: null, serviceUrl: null, dbName: null, error: null }
+      : { state: 'removed', serviceId: null, serviceUrl: null, error: `The sandbox app was removed, but its database ${sb.dbName} is still inside your app’s database server.` });
+  }
+  return { removed: true };
+}
+
+module.exports = { standupSandbox, removeSandbox, sandboxDatabase, recordSandbox, withDatabase };

package/scripts/bongos/provision-render.js

@@ -34,6 +34,7 @@
 const { RenderApi } = require('./render-api.js');
 const payload = require('./render-payload.js');
 const { parseTargetRef } = require('./provision-repo-auth.js');
+const sandbox = require('./provision-render-sandbox.js');
 
 // A key waiting longer than this was lent for a run that never came. It is refused and
 // cleared rather than spent late.
@@ -147,7 +148,18 @@ async function renderStandupInstance(inst, deps, intent) {
     const owners = await api.listOwners();
     if (!owners.some((o) => o.id === host.ownerId)) return refuse(`this Render key cannot reach workspace ${host.ownerId}`);
 
-    return host.mode === 'adopt' ? await adopt(api, inst, host, deps) : await greenfield(api, inst, host, deps);
+    // An app already up that only asked for its sandbox (render-sandbox.js
+    // enqueueSandboxAdd) is not touched again: the run goes straight to the sandbox.
+    const sandboxOnly = !!(host.sandboxWanted && host.sandbox && host.sandbox.state === 'requested'
+      && host.serviceId && ['deploying', 'linked', 'live'].includes(host.state));
+    const app = sandboxOnly ? { ok: true } : (host.mode === 'adopt' ? await adopt(api, inst, host, deps) : await greenfield(api, inst, host, deps));
+    // The sandbox (ADR 0406, task 1005289): after the app, with the same key. Its failure
+    // is recorded on the sandbox and never fails the app.
+    if (app.ok && host.sandboxWanted) {
+      const fresh = deps.provisioning && deps.provisioning.getInstanceById ? ((await deps.provisioning.getInstanceById(db, inst.id)) || inst) : inst;
+      await sandbox.standupSandbox(api, fresh, { ...host, ...(fresh.app_host || {}) }, deps);
+    }
+    return app;
   } catch (e) {
     return refuse(plainReason(e));
   } finally {
@@ -190,9 +202,32 @@ async function afterProvision(inst, deps, intent, result) {
 // Teardown's half (ADR 0327 §3): forget the Render app, never delete it. The ids stay on
 // the row so an operator can still say which services were the project's; the owner
 // deletes them in their own Render dashboard if they want to stop paying.
-async function forgetRenderApp(inst, { db, log, apply }) {
+//
+// The SANDBOX is the one exception (ADR 0406 §7, task 1005289): the platform made it, so
+// the platform removes it — when the owner lent their key with the teardown (the running
+// teardown intent's borrowed_key_enc). The key is cleared here whatever happens.
+async function forgetRenderApp(inst, deps) {
+  const { db, log, apply } = deps;
   const host = inst.app_host;
   if (!host || host.platform !== 'render') return;
+  if (host.sandbox) {
+    let keyEnc = null, intentId = null;
+    try {
+      const { rows } = await db.query(
+        `SELECT id, borrowed_key_enc FROM provisioning_intents
+          WHERE instance_id = $1 AND action = 'teardown' AND state IN ('pending', 'running') AND borrowed_key_enc IS NOT NULL
+          ORDER BY created_at DESC LIMIT 1`, [inst.id]);
+      if (rows && rows[0]) { keyEnc = rows[0].borrowed_key_enc; intentId = rows[0].id; }
+      const secretBox = deps.secretBox || require('../../src/bongos/secret-box');
+      const api = keyEnc && host.ownerId ? renderApiFor(deps, secretBox.decrypt(keyEnc), host.ownerId) : null;
+      await sandbox.removeSandbox(inst, deps, api);
+    } catch (e) {
+      log(`  (sandbox not removed: ${e && e.message})`);
+      if (apply) await sandbox.recordSandbox(db, inst.id, { state: 'left', error: `The sandbox could not be removed, so it is still on your Render account: ${String((e && e.message) || e).split('\n')[0].slice(0, 200)}` }).catch(() => {});
+    } finally {
+      if (intentId != null) await clearBorrowedKey(db, intentId);
+    }
+  }
   const what = [host.serviceId && `service ${host.serviceId}`, host.postgresId && `database ${host.postgresId}`].filter(Boolean).join(' and ') || 'nothing yet';
   log(`  [render] ${apply ? 'disconnected' : 'would disconnect'} from Render (${what}); nothing on Render is deleted — the owner removes it in their own dashboard`);
   if (apply) await recordAppHost(db, inst.id, { state: 'disconnected' });

package/scripts/bongos/provision-teardown.js

@@ -40,7 +40,7 @@ async function teardownInstance(inst, deps) {
   if (inst.db_name) log(`  (left for the operator: dropdb ${dbName(inst)}, prune ${CONFIG.backupDir}/${dbName(inst)}-*.sql.gz)`);
   parkAddress(inst, { controlExec, log, apply });
   // The app's Render services are the OWNER's: forget them, never delete them (ADR 0327 §3, task 1004183).
-  await require('./provision-render.js').forgetRenderApp(inst, { db, log, apply });
+  await require('./provision-render.js').forgetRenderApp(inst, { ...deps, db, log, apply }); // …except the sandbox, removed when a key came with the teardown (ADR 0406 §7)
   // Revoke the instance's deploy key (ADR 0176) and remove its local halves. The
   // checkout itself is deliberately left in place (data is precious), so the key
   // files must NOT ride along — and a revoke skip must be LOUD: a torn-down project

package/scripts/bongos/render-api.js

@@ -24,9 +24,13 @@
 // resource through the guard, so nothing is ever sent to or read from a resource whose
 // workspace was not checked.
 //
-// NO DELETE. The platform must not hold the ability to destroy infrastructure in an
-// account it does not own (ADR 0327 §3). There is no delete method, and _req refuses the
-// verb outright, so adding one later is a visible change to this file, not a one-liner.
+// NO DELETE — with ONE narrow exception. The platform must not hold the ability to destroy
+// infrastructure in an account it does not own (ADR 0327 §3), and _req refuses the verb
+// outright. The exception is the project's SANDBOX (ADR 0406 §7, task 1005289): a free
+// service the platform itself created, removed when the owner tears the project down with
+// their key lent. deleteSandboxService reads the service through the guard first and
+// refuses anything not named `…-sandbox` on the free plan, so it can never reach the
+// owner's live app; it is the only path to a DELETE in this file.
 
 'use strict';
 
@@ -133,6 +137,32 @@ class RenderApi extends JsonHttpApi {
     return this._req('PUT', `/services/${encodeURIComponent(serviceId)}/env-vars/${encodeURIComponent(key)}`, { value }, { dryRunResult: { key } });
   }
 
+  // The service of this exact name in this workspace, or null. Lets a re-run find a
+  // sandbox an earlier run created before its id reached the row, instead of making a
+  // second one. Every element of the list is checked through the guard.
+  async findServiceByName(name) {
+    const q = `/services?name=${encodeURIComponent(name)}&ownerId=${encodeURIComponent(this.ownerId)}&limit=20`;
+    const json = await this._req('GET', q, null, { dryRunResult: { items: [] } });
+    const items = Array.isArray(json) ? json : (json && json.items) || [];
+    const found = items.map((e) => (e && e.service) || e).filter((s) => s && typeof s.id === 'string');
+    found.forEach((s) => this.assertOwned(s, `service ${s.id}`));
+    return found.find((s) => s.name === name) || null;
+  }
+
+  // Remove a project's SANDBOX service — and nothing else (see the header). The service is
+  // read through the workspace guard, and refused unless it is named `…-sandbox` AND on
+  // the free plan: the owner's live app is never either.
+  async deleteSandboxService(serviceId) {
+    const svc = await this.getService(serviceId);
+    const plan = svc.serviceDetails && svc.serviceDetails.plan;
+    if (!/-sandbox$/.test(String(svc.name || '')) || plan !== 'free') {
+      throw new RenderApiError(`refusing to delete service ${serviceId}: it is not a free sandbox the platform created (ADR 0406 §7)`);
+    }
+    const path = `/services/${encodeURIComponent(serviceId)}`;
+    if (this.dryRun) { this.log(`[dry-run] Render DELETE ${path}`); return { dryRun: true }; }
+    return super._req('DELETE', path, null);
+  }
+
   async triggerDeploy(serviceId) {
     await this.getService(serviceId);
     return this._req('POST', `/services/${encodeURIComponent(serviceId)}/deploys`, {}, { dryRunResult: { id: null } });

package/scripts/bongos/render-payload.js

@@ -82,4 +82,42 @@ function renderServicePayload(inst, { ownerId, repoUrl, branch, webPlan, region,
   };
 }
 
-module.exports = { DEFAULTS, resourceName, plansFor, buildFor, renderPostgresPayload, renderServicePayload };
+// POST /services, for the project's SANDBOX (ADR 0406, task 1005289): the same repository
+// and build as the app, on Render's FREE plan, following `main` on every merge. It runs
+// with BONGOS_SANDBOX=1 so the app (and the starter's outbound gate, task 1005291) knows
+// it is not the live site. `dbUrl` is the sandbox's OWN database, never the live one.
+const SANDBOX_SUFFIX = 'sandbox';
+function sandboxServicePayload(inst, { ownerId, repoUrl, region, build, dbUrl }) {
+  const p = renderServicePayload(inst, { ownerId, repoUrl, branch: 'main', webPlan: 'free', region, build, dbUrl });
+  p.name = resourceName(inst, SANDBOX_SUFFIX);
+  p.autoDeploy = 'yes';
+  p.envVars = [{ key: 'BONGOS_SANDBOX', value: '1' }, ...p.envVars];
+  return p;
+}
+
+// The sandbox's database name inside the app's own database server: the project's slug
+// with underscores, ending `_sandbox`. Checked against a strict shape because it is put
+// into a CREATE / DROP DATABASE statement as an identifier.
+const SANDBOX_DB_RE = /^[a-z][a-z0-9_]{0,40}_sandbox$/;
+function sandboxDbName(inst) {
+  let base = resourceName(inst).replace(/-/g, '_').replace(/^[^a-z]+/, '').slice(0, 40);
+  if (!base) base = `project_${Number(inst.id) || 0}`;
+  const name = `${base}_sandbox`;
+  if (!SANDBOX_DB_RE.test(name)) throw new Error(`could not make a safe sandbox database name from '${inst.slug}'`);
+  return name;
+}
+
+// How an adopted service is built, read off Render's own answer, so the sandbox copies
+// it (ADR 0406 §7: "the sandbox is a new free service copying its build settings").
+// Returns null when the answer does not say enough to copy.
+function buildFromService(svc) {
+  const d = (svc && svc.serviceDetails) || {};
+  const runtime = d.runtime || d.env;
+  if (!RUNTIMES.includes(runtime)) return null;
+  if (runtime === 'docker') return { runtime: 'docker' };
+  const e = d.envSpecificDetails || {};
+  if (!e.startCommand) return null;
+  return { runtime, buildCommand: e.buildCommand || BUILD_DEFAULTS[runtime], startCommand: e.startCommand };
+}
+
+module.exports = { DEFAULTS, resourceName, plansFor, buildFor, renderPostgresPayload, renderServicePayload, sandboxServicePayload, sandboxDbName, buildFromService, SANDBOX_DB_RE };

package/scripts/gds/first-read.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// scripts/gds/first-read.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/first-read.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
+'use strict';
+require('../bongos/forwarder.js').forward(module, 'first-read.js');

package/scripts/gds/provision-render-sandbox.js

@@ -0,0 +1,6 @@
+// scripts/gds/provision-render-sandbox.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/provision-render-sandbox.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
+'use strict';
+require('../bongos/forwarder.js').forward(module, 'provision-render-sandbox.js');

package/src/module-api.js

@@ -81,7 +81,7 @@ const { sleep } = require('./sleep');
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.25.16'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.25.17'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');