index.js

// A notes app backed by managed Postgres.
//
// The point of this template is the wiring: how an app on velixir finds its database, keeps
// its schema in step, and stays healthy. The notes themselves are the least interesting part.
//
// Deploy it from the velixir gallery and a managed Postgres is created and bound for you, so
// DATABASE_URL is in the environment on the first boot. Nothing here hardcodes a host, so the
// same code runs locally against a container and in production against the managed instance.

const express = require('express');
const { Pool } = require('pg');
const { pgConfig } = require('./db');

const app = express();
const port = process.env.PORT || 8080;
const connectionString = process.env.DATABASE_URL;

app.use(express.urlencoded({ extended: false }));
app.use(express.json());

// The process runs as PID 1 in its container (the Procfile starts node directly, so a redeploy's
// SIGTERM reaches it rather than stopping at npm). PID 1 gets no default signal handling, though:
// without this it would ignore SIGTERM and only go when the platform's grace period ran out.
// Finish what is in flight, then go.
function stopOnSignal(server, cleanup = async () => {}) {
  for (const signal of ['SIGTERM', 'SIGINT']) {
    process.once(signal, () => {
      server.close(() => cleanup().finally(() => process.exit(0)));
      server.closeIdleConnections(); // idle keep-alive sockets would otherwise hold close() open
      setTimeout(() => process.exit(0), 10000).unref();
    });
  }
}

// Everything that reaches the browser goes through this. Notes are user input, so they are
// escaped on the way out rather than trusted.
const escapeHtml = (s) =>
  String(s).replace(/[&<>"']/g, (c) => ({
    '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
  })[c]);

// ─── Setup mode ─────────────────────────────────────────────────────────────

// No database bound yet. Rather than exiting (a crash loop reads as "the platform is
// broken"), serve a page that says exactly what is missing and how to fix it, and keep the
// health check green so the page stays reachable.
if (!connectionString) {
  console.log(
    'DATABASE_URL is not set, so this app is serving its setup page.\n' +
    'On velixir: create a managed Postgres, bind it to this app as DATABASE_URL, then redeploy.\n' +
    'Locally: DATABASE_URL=postgres://user:pass@localhost:5432/notes npm start'
  );

  app.get('/healthz', (_req, res) => res.type('text/plain').send('ok (setup mode: no database bound)'));
  app.use('/api', (_req, res) =>
    res.status(503).json({ error: 'No database is bound to this app yet. Bind a managed Postgres as DATABASE_URL and redeploy.' }));
  app.use((_req, res) => res.type('text/html').send(page('Connect a database', setupBody())));

  stopOnSignal(app.listen(port, '0.0.0.0', () => console.log(`setup page listening on ${port}`)));
  return; // CommonJS allows a top-level return; nothing below runs without a database.
}

// ─── Database ───────────────────────────────────────────────────────────────

const pool = new Pool({
  // See db.js: velixir's sslmode=require means "encrypt, do not verify", which node-postgres
  // does not do on its own.
  ...pgConfig(connectionString),
  // Keep the pool small. An app that scales to several replicas multiplies this by the
  // replica count, and a managed instance has a connection cap.
  max: 5,
});

// A broken connection in the idle pool emits here. Without a listener it crashes the process.
pool.on('error', (err) => console.error('idle database connection failed:', err.message));

const state = { ready: false, lastError: null };

// Migrating on boot is fine for one table and one replica. Past that, run migrations as a
// deliberate step instead: several replicas starting at once will race this.
async function migrate() {
  await pool.query(`
    CREATE TABLE IF NOT EXISTS notes (
      id         BIGSERIAL PRIMARY KEY,
      body       TEXT NOT NULL,
      created_at TIMESTAMPTZ NOT NULL DEFAULT now()
    )
  `);
}

// Keep trying rather than exiting. A database that is briefly unreachable (a failover, a
// rotated password waiting for a redeploy) gets an explanation on the page instead of a
// crash loop, and the app recovers by itself when the database comes back.
async function connect(attempt = 1) {
  try {
    await migrate();
    state.ready = true;
    state.lastError = null;
    console.log('database ready');
  } catch (err) {
    state.lastError = err.message;
    if (attempt === 1 || attempt % 12 === 0) {
      console.error(`database not reachable yet (attempt ${attempt}): ${err.message}`);
    }
    setTimeout(() => connect(attempt + 1), 5000);
  }
}

// ─── Health ─────────────────────────────────────────────────────────────────

// Liveness AND readiness: this app is useless without its database, so a failed query takes
// it out of rotation rather than letting it serve errors.
app.get('/healthz', async (_req, res) => {
  if (!state.ready) return res.status(503).type('text/plain').send('waiting for the database');
  try {
    await pool.query('SELECT 1');
    res.type('text/plain').send('ok');
  } catch (err) {
    console.error('health check failed:', err.message);
    res.status(503).type('text/plain').send('database unreachable');
  }
});

// Until the first successful connection, every other route explains the wait. The driver's
// error stays in the log: it can name the database's internal address and user, which is
// nobody else's business.
app.use((req, res, next) => {
  if (state.ready) return next();
  if (req.path.startsWith('/api/')) {
    return res.status(503).json({ error: 'Waiting for the database. The app log has the details.' });
  }
  res.status(503).type('text/html').send(page('Waiting for the database', waitingBody()));
});

// ─── API ────────────────────────────────────────────────────────────────────

// Express 5 passes a rejected promise from an async handler to the error handler at the
// bottom. (Express 4 did not: the rejection went unhandled, and on current Node that ends
// the process, so one failed query during a database restart took the whole app down.)

app.get('/api/notes', async (_req, res) => {
  const { rows } = await pool.query(
    'SELECT id, body, created_at FROM notes ORDER BY created_at DESC LIMIT 100'
  );
  res.json(rows);
});

app.post('/api/notes', async (req, res) => {
  const body = (req.body?.body ?? '').toString().trim();
  if (!body) return res.status(400).json({ error: 'body is required' });

  // Parameterised, always. String-building a query with user input is how this kind of
  // app ends up owned.
  const { rows } = await pool.query(
    'INSERT INTO notes (body) VALUES ($1) RETURNING id, body, created_at',
    [body.slice(0, 2000)]
  );
  res.status(201).json(rows[0]);
});

app.post('/notes', async (req, res) => {
  const body = (req.body?.body ?? '').toString().trim();
  if (body) {
    await pool.query('INSERT INTO notes (body) VALUES ($1)', [body.slice(0, 2000)]);
  }
  res.redirect('/');
});

app.post('/notes/:id/delete', async (req, res) => {
  const id = Number.parseInt(req.params.id, 10);
  if (Number.isSafeInteger(id)) await pool.query('DELETE FROM notes WHERE id = $1', [id]);
  res.redirect('/');
});

app.get('/', async (_req, res) => {
  const { rows } = await pool.query(
    'SELECT id, body, created_at FROM notes ORDER BY created_at DESC LIMIT 100'
  );
  res.type('text/html').send(page('Notes on velixir', notesBody(rows)));
});

app.use((err, _req, res, _next) => {
  console.error(err);
  res.status(500).type('text/plain').send('Something went wrong.');
});

// ─── Pages ──────────────────────────────────────────────────────────────────

function notesBody(notes) {
  const items = notes.length
    ? notes.map((n) => `
        <li>
          <div>
            <p>${escapeHtml(n.body)}</p>
            <time>${new Date(n.created_at).toISOString().replace('T', ' ').slice(0, 19)} UTC</time>
          </div>
          <form method="post" action="/notes/${n.id}/delete">
            <button type="submit" class="del" aria-label="Delete note">&times;</button>
          </form>
        </li>`).join('')
    : '<li class="empty">No notes yet. Write one above.</li>';

  return `
  <h1>Notes</h1>
  <p class="sub">Stored in managed Postgres, reached through <code>DATABASE_URL</code>.</p>

  <form class="new" method="post" action="/notes">
    <input type="text" name="body" placeholder="Write a note" maxlength="2000" required autofocus>
    <button type="submit">Add</button>
  </form>

  <ul>${items}</ul>`;
}

function setupBody() {
  return `
  <h1>Connect a database</h1>
  <p class="sub">This app keeps its notes in Postgres, and no database is bound to it yet.</p>
  <ol class="steps">
    <li><strong>Create a managed Postgres</strong> from the Databases page, or run
      <code>velixir db create</code>.</li>
    <li><strong>Bind it to this app</strong> as <code>DATABASE_URL</code>: on the database's page
      under Bound apps, or <code>velixir db bind &lt;database-id&gt; --app &lt;app-id&gt;</code>.</li>
    <li><strong>Redeploy</strong> with the Redeploy button on the live release (Deploys tab).
      The table is created on the next boot.</li>
  </ol>
  <p class="note">Deploying this template from the velixir gallery does all three for you.</p>`;
}

function waitingBody() {
  return `
  <h1>Waiting for the database</h1>
  <p class="sub">The app is running and retrying the connection every few seconds. The app log says why it cannot connect.</p>
  <p class="note">If the database password was rotated, redeploy the app to pick up the new one.</p>`;
}

function page(title, body) {
  return `<!doctype html>
<html lang="en">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>${escapeHtml(title)}</title>
<style>
  :root { color-scheme: dark; }
  * { box-sizing: border-box; }
  body { margin:0; min-height:100vh; background:#0b0b10; color:#e8e8ef;
         font:15px/1.6 ui-sans-serif,system-ui,-apple-system,Segoe UI,sans-serif; }
  .wrap { max-width:38rem; margin:0 auto; padding:3rem 1.25rem 4rem; }
  h1 { font-size:1.5rem; margin:0 0 .25rem; letter-spacing:-.02em; }
  .sub { color:#7a7a8c; font-size:.8125rem; margin:0 0 2rem; }
  code { background:#16161f; border:1px solid #26263a; border-radius:5px;
         padding:.1rem .35rem; color:#c7d2fe; font-size:.8125rem; overflow-wrap:anywhere; }
  form.new { display:flex; gap:.5rem; margin-bottom:2rem; }
  input[type=text] { flex:1; min-width:0; padding:.7rem .85rem; border-radius:8px; background:#13131c;
                     border:1px solid #26263a; color:#e8e8ef; font:inherit; }
  input[type=text]:focus { outline:none; border-color:#6366f1; }
  button { padding:.7rem 1.1rem; border-radius:8px; border:0; background:#6366f1;
           color:#fff; font:inherit; font-weight:600; cursor:pointer; }
  ul { list-style:none; margin:0; padding:0; }
  ul li { display:flex; align-items:flex-start; justify-content:space-between; gap:1rem;
          border:1px solid #1f1f2e; border-radius:10px; padding:.875rem 1rem; margin-bottom:.5rem; }
  ul li p { margin:0; overflow-wrap:anywhere; }
  ul li time { color:#4b4b5c; font-size:.75rem; font-variant-numeric:tabular-nums; }
  ul li.empty { color:#4b4b5c; justify-content:center; border-style:dashed; }
  button.del { background:transparent; color:#4b4b5c; padding:.15rem .45rem; font-size:1.1rem; }
  button.del:hover { color:#fca5a5; }
  ol.steps { padding-left:1.25rem; margin:0 0 1.5rem; }
  ol.steps li { margin-bottom:.9rem; }
  .note { color:#7a7a8c; font-size:.8125rem; }
  footer { color:#4b4b5c; font-size:.75rem; margin-top:2.5rem; text-align:center; }
  footer a { color:#7a7a8c; }
</style>
<div class="wrap">
  ${body}
  <footer>
    <a href="/api/notes">JSON API</a> &middot; running on <a href="https://velixir.net">velixir</a>
  </footer>
</div>
</html>`;
}

// ─── Start ──────────────────────────────────────────────────────────────────

// Listen first, then connect: the waiting page needs a server to be seen on.
// 0.0.0.0, not localhost: the platform health check comes from outside the container.
const server = app.listen(port, '0.0.0.0', () => {
  console.log(`listening on ${port}`);
  connect();
});
stopOnSignal(server, () => pool.end());