declapract-typescript-ehmpathy 0.49.14 → 0.50.0

package/dist/.test/assets/git/declarations/practices/persist-with-rds/best-practice/src/utils/database/asDatabaseClientSsl.ts

@@ -0,0 +1,52 @@
+import { ConstraintError } from 'helpful-errors';
+
+import { type ConnectionOptions, checkServerIdentity } from 'node:tls';
+import { RDS_CA_BUNDLE_US_EAST_1 } from './rdsCaBundleUsEast1';
+
+/**
+ * .what = the aws region an rds endpoint lives in, read from its dns name
+ * .why = the ca bundle is per region, so the region decides which roots verify the cluster
+ */
+const asRdsEndpointRegion = (input: { endpoint: string }): string | null =>
+  /\.(?<region>[a-z]{2}(?:-[a-z]+)+-\d+)\.rds\.amazonaws\.com$/.exec(
+    input.endpoint,
+  )?.groups?.region ?? null;
+
+/**
+ * .what = the tls options a pg client connects with, derived from the cluster endpoint
+ * .why = a cloud cluster is reached encrypted and verified (verify-full), so the connection
+ *        works whether or not the cluster forces ssl, and never trusts an impostor.
+ *        the local testdb declares no cluster endpoint and speaks no tls, so it connects plain
+ * .note = the name check pins to the cluster endpoint, never the dialed host: a local tunnel
+ *         dials an ssm proxy alias the certificate does not carry, and pg@8 overwrites any
+ *         servername option with the dialed host (lib/connection.js)
+ * .note = only the us-east-1 roots ship here. an endpoint in any other region fails loud, so a
+ *         cluster is never dialed with roots that cannot verify it
+ */
+export const asDatabaseClientSsl = (input: {
+  clusterEndpoint: string | null;
+}): ConnectionOptions | false => {
+  // no cluster endpoint declared, so this is the local testdb, which speaks no tls
+  if (!input.clusterEndpoint) return false;
+  const clusterEndpoint = input.clusterEndpoint;
+
+  // only the us-east-1 roots ship, so any other region must add its own bundle first
+  const region = asRdsEndpointRegion({ endpoint: clusterEndpoint });
+  if (region !== 'us-east-1')
+    throw new ConstraintError(
+      'the cluster endpoint is not in us-east-1, so no ca bundle here can verify it',
+      {
+        clusterEndpoint,
+        region,
+        hint: `add the rds ca bundle for that region (https://truststore.pki.rds.amazonaws.com/<region>/<region>-bundle.pem) beside rdsCaBundleUsEast1.ts, and pick it by region here`,
+      },
+    );
+
+  // verify the chain against the rds roots, and the name against the cluster endpoint
+  return {
+    ca: RDS_CA_BUNDLE_US_EAST_1,
+    rejectUnauthorized: true,
+    checkServerIdentity: (_hostDialed, cert) =>
+      checkServerIdentity(clusterEndpoint, cert),
+  };
+};

package/dist/.test/assets/git/declarations/practices/persist-with-rds/best-practice/src/utils/database/databaseClientTimeouts.ts

@@ -0,0 +1,14 @@
+import { toMilliseconds } from 'iso-time';
+
+/**
+ * .what = the connect and query bounds every pg client in this service carries
+ * .why = pg's defaults wait forever. a cluster that accepts the socket and never
+ *        answers — the shape of a major-version flip — would otherwise hold each
+ *        lambda for its full timeout, at full concurrency
+ * .note = connect outlasts an aurora serverless v2 resume from zero acu (~15s);
+ *         query sits under the lambda timeout so the error surfaces, never a kill
+ */
+export const databaseClientTimeouts = {
+  connectionTimeoutMillis: toMilliseconds({ seconds: 20 }),
+  query_timeout: toMilliseconds({ seconds: 30 }),
+};

package/dist/.test/assets/git/declarations/practices/persist-with-rds/best-practice/src/utils/database/getOneDatabaseConnection.integration.test.ts

@@ -0,0 +1,10 @@
+import { getOneDatabaseConnection } from './getOneDatabaseConnection';
+
+describe('getOneDatabaseConnection', () => {
+  it('should be able to connect and execute a query', async () => {
+    const dbConnection = await getOneDatabaseConnection();
+    const result = await dbConnection.query({ sql: 'select 1' });
+    expect(result.rows.length).toEqual(1);
+    await dbConnection.end();
+  });
+});

package/dist/.test/assets/git/declarations/practices/persist-with-rds/best-practice/src/utils/database/getOneDatabaseConnection.ts

@@ -0,0 +1,119 @@
+import { HelpfulError, UnexpectedCodePathError } from 'helpful-errors';
+import pg, { Client, type QueryResult, type QueryResultRow } from 'pg';
+
+import { getConfig } from '@src/utils/config/getConfig';
+import { getEnvironment } from '@src/utils/environment';
+
+import { asDatabaseClientSsl } from './asDatabaseClientSsl';
+import { databaseClientTimeouts } from './databaseClientTimeouts';
+import { getOneDatabasePort } from './getOneDatabasePort';
+
+// https://github.com/brianc/node-postgres/pull/353#issuecomment-283709264
+pg.types.setTypeParser(20, (value) => parseInt(value, 10)); // cast bigints to numbers; by default, pg returns bigints as strings, since max val of bigint is bigger than max safe value in js
+pg.types.setTypeParser(1700, (value) => parseFloat(value)); // cast numerics to numbers; by default, pg returns numerics as strings
+
+export interface DatabaseConnection {
+  query: <Row extends QueryResultRow>(args: {
+    sql: string;
+    values?: unknown[];
+  }) => Promise<QueryResult<Row>>;
+  end: () => Promise<void>;
+}
+
+export class DatabaseQueryError extends HelpfulError {
+  constructor({
+    sql,
+    values,
+    caught,
+  }: {
+    sql: string;
+    values?: unknown[];
+    caught: Error;
+  }) {
+    const message = `
+caught error querying database: ${caught.message}
+
+sql:
+  ${sql.trim()}
+
+values:
+  ${JSON.stringify(values)}
+    `.trim();
+    super(message, { sql, values, cause: caught });
+  }
+}
+
+/**
+ * .what = opens one pg client on the tunnel for this environment, encrypted and bounded
+ * .why = the one place the app builds a pg client, so every connection carries the same tls,
+ *        the same timeouts, and the same DatabaseQueryError
+ * .note = mode 'readonly' reads config under the plan grant and connects as the cicd for-plan
+ *         role, then marks the session read only. the session mode is a guard against a slip,
+ *         not a security boundary: a query can still flip it back. the boundary is the for-plan
+ *         role's own grants
+ */
+export const getOneDatabaseConnection = async (
+  input: { mode: 'readwrite' | 'readonly' } = { mode: 'readwrite' },
+): Promise<DatabaseConnection> => {
+  const environment = await getEnvironment();
+
+  // read the config under the grant the mode needs; readonly never reads a write credential
+  const config =
+    input.mode === 'readonly'
+      ? await getConfig({ grant: 'plan' })
+      : await getConfig();
+  const target = config.database.target;
+  const role =
+    input.mode === 'readonly'
+      ? config.database.role.cicd['for-plan']
+      : config.database.role.crud;
+
+  // determine which tunnel to use based on environment.server
+  const tunnel =
+    environment.server === 'cloud@aws.lambda'
+      ? config.database.tunnel.lambda
+      : config.database.tunnel.local;
+
+  // ensure tunnel is defined for the requested server
+  if (!tunnel) {
+    throw new UnexpectedCodePathError(
+      `Database tunnel not configured for environment.server + env.access`,
+      { environment },
+    );
+  }
+
+  // instantiate the client, encrypted and verified wherever a cluster endpoint is declared
+  const client = new Client({
+    host: tunnel.host,
+    port: getOneDatabasePort({
+      access: environment.access,
+      portDeclared: tunnel.port,
+    }), // a worktree's testdb binds a port of its own; the test harness declares it via TESTDB_PORT
+    user: role.username,
+    password: role.password,
+    database: target.database,
+    ssl: asDatabaseClientSsl({
+      clusterEndpoint: config.database.tunnel.lambda?.host ?? null,
+    }),
+    ...databaseClientTimeouts,
+  });
+  await client.connect();
+  await client.query(`SET search_path TO ${target.schema}, public;`); // https://www.postgresql.org/docs/current/ddl-schemas.html#DDL-SCHEMAS-
+
+  // mark a readonly session read only, so a write from it fails loud
+  if (input.mode === 'readonly')
+    await client.query('SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY;');
+
+  // declare our interface
+  return {
+    query: (args: { sql: string; values?: unknown[] }) =>
+      client.query(args.sql, args.values).catch((error) => {
+        throw new DatabaseQueryError({
+          sql: args.sql,
+          values: args.values,
+          caught: error,
+        });
+      }),
+    end: () => client.end(),
+  };
+};

package/dist/.test/assets/git/declarations/practices/persist-with-rds/best-practice/src/utils/database/getOneDatabasePort.ts

@@ -0,0 +1,30 @@
+import { ConstraintError } from 'helpful-errors';
+
+/**
+ * .what = the host port a connection to the database should dial, for an access
+ * .why = a worktree's local testdb binds a port of its own, so the test harness declares that
+ *        port via TESTDB_PORT and the app dials it. the override is honored ONLY with test access,
+ *        so a stray TESTDB_PORT can never redirect a prep or prod connection
+ * .note = absent TESTDB_PORT, or any access other than test, keeps the declared port
+ */
+export const getOneDatabasePort = (
+  input: { access: string; portDeclared: number },
+  context: { env: NodeJS.ProcessEnv } = { env: process.env },
+): number => {
+  // only test access reaches the local testdb; every other access keeps its declared port
+  if (input.access !== 'test') return input.portDeclared;
+
+  // no override declared; the testdb binds the declared port
+  const portOverride = context.env.TESTDB_PORT;
+  if (portOverride === undefined || portOverride === '')
+    return input.portDeclared;
+
+  // a malformed override fails loud, so a typo never dials a port no db binds
+  const port = Number(portOverride);
+  if (!/^[0-9]+$/.test(portOverride) || port <= 0 || port > 65535)
+    throw new ConstraintError('TESTDB_PORT is not a valid port', {
+      portOverride,
+      hint: 'set TESTDB_PORT to a positive integer port, or unset it to dial the declared port',
+    });
+  return port;
+};

package/dist/.test/assets/git/declarations/practices/persist-with-rds/best-practice/src/utils/database/rdsCaBundleUsEast1.test.ts

@@ -0,0 +1,51 @@
+import { given, then, useBeforeAll, when } from 'test-fns';
+
+import { X509Certificate } from 'node:crypto';
+import { RDS_CA_BUNDLE_US_EAST_1 } from './rdsCaBundleUsEast1';
+
+/**
+ * .what = split a pem bundle into one pem per certificate
+ * .why = node parses exactly one certificate per X509Certificate
+ */
+const asPemCertificates = (input: { bundle: string }): string[] =>
+  input.bundle.match(
+    /-----BEGIN CERTIFICATE-----[\s\S]+?-----END CERTIFICATE-----/g,
+  ) ?? [];
+
+/**
+ * .what = the common name a certificate's subject declares
+ * .why = the subject is one multi-line string; the CN line names the root
+ */
+const asCommonName = (input: { cert: X509Certificate }): string | null =>
+  input.cert.subject
+    .split('\n')
+    .find((line) => line.startsWith('CN='))
+    ?.slice('CN='.length) ?? null;
+
+describe('RDS_CA_BUNDLE_US_EAST_1', () => {
+  given('[case1] the embedded bundle', () => {
+    when('[t0] each certificate in it is parsed', () => {
+      const scene = useBeforeAll(async () => ({
+        certs: asPemCertificates({ bundle: RDS_CA_BUNDLE_US_EAST_1 }).map(
+          (pem) => new X509Certificate(pem),
+        ),
+      }));
+
+      then('it holds the three us-east-1 roots', () => {
+        expect(scene.certs.map((cert) => asCommonName({ cert }))).toEqual([
+          'Amazon RDS us-east-1 Root CA RSA2048 G1',
+          'Amazon RDS us-east-1 Root CA RSA4096 G1',
+          'Amazon RDS us-east-1 Root CA ECC384 G1',
+        ]);
+      });
+
+      then('each is a certificate authority that signed itself', () => {
+        for (const cert of scene.certs) {
+          expect(cert.ca).toEqual(true);
+          expect(cert.checkIssued(cert)).toEqual(true);
+          expect(cert.verify(cert.publicKey)).toEqual(true);
+        }
+      });
+    });
+  });
+});

package/dist/.test/assets/git/declarations/practices/persist-with-rds/best-practice/src/utils/database/rdsCaBundleUsEast1.ts

@@ -0,0 +1,86 @@
+/**
+ * .what = the aws rds root certificate authorities for us-east-1, as pem
+ * .why = verify-full checks the cluster's certificate against these roots, so a client
+ *        encrypts and knows it reached the real cluster rather than an impostor.
+ *        embedded as a constant, never a .pem file, so the lambda bundle always carries it
+ * .note = source: https://truststore.pki.rds.amazonaws.com/us-east-1/us-east-1-bundle.pem
+ *         roots: RSA2048 G1 (until 2061), RSA4096 G1 (until 2121), ECC384 G1 (until 2121)
+ */
+export const RDS_CA_BUNDLE_US_EAST_1 = `
+-----BEGIN CERTIFICATE-----
+MIID/zCCAuegAwIBAgIRAPVSMfFitmM5PhmbaOFoGfUwDQYJKoZIhvcNAQELBQAw
+gZcxCzAJBgNVBAYTAlVTMSIwIAYDVQQKDBlBbWF6b24gV2ViIFNlcnZpY2VzLCBJ
+bmMuMRMwEQYDVQQLDApBbWF6b24gUkRTMQswCQYDVQQIDAJXQTEwMC4GA1UEAwwn
+QW1hem9uIFJEUyB1cy1lYXN0LTEgUm9vdCBDQSBSU0EyMDQ4IEcxMRAwDgYDVQQH
+DAdTZWF0dGxlMCAXDTIxMDUyNTIyMzQ1N1oYDzIwNjEwNTI1MjMzNDU3WjCBlzEL
+MAkGA1UEBhMCVVMxIjAgBgNVBAoMGUFtYXpvbiBXZWIgU2VydmljZXMsIEluYy4x
+EzARBgNVBAsMCkFtYXpvbiBSRFMxCzAJBgNVBAgMAldBMTAwLgYDVQQDDCdBbWF6
+b24gUkRTIHVzLWVhc3QtMSBSb290IENBIFJTQTIwNDggRzExEDAOBgNVBAcMB1Nl
+YXR0bGUwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDu9H7TBeGoDzMr
+dxN6H8COntJX4IR6dbyhnj5qMD4xl/IWvp50lt0VpmMd+z2PNZzx8RazeGC5IniV
+5nrLg0AKWRQ2A/lGGXbUrGXCSe09brMQCxWBSIYe1WZZ1iU1IJ/6Bp4D2YEHpXrW
+bPkOq5x3YPcsoitgm1Xh8ygz6vb7PsvJvPbvRMnkDg5IqEThapPjmKb8ZJWyEFEE
+QRrkCIRueB1EqQtJw0fvP4PKDlCJAKBEs/y049FoOqYpT3pRy0WKqPhWve+hScMd
+6obq8kxTFy1IHACjHc51nrGII5Bt76/MpTWhnJIJrCnq1/Uc3Qs8IVeb+sLaFC8K
+DI69Sw6bAgMBAAGjQjBAMA8GA1UdEwEB/wQFMAMBAf8wHQYDVR0OBBYEFE7PCopt
+lyOgtXX0Y1lObBUxuKaCMA4GA1UdDwEB/wQEAwIBhjANBgkqhkiG9w0BAQsFAAOC
+AQEAFj+bX8gLmMNefr5jRJfHjrL3iuZCjf7YEZgn89pS4z8408mjj9z6Q5D1H7yS
+jNETVV8QaJip1qyhh5gRzRaArgGAYvi2/r0zPsy+Tgf7v1KGL5Lh8NT8iCEGGXwF
+g3Ir+Nl3e+9XUp0eyyzBIjHtjLBm6yy8rGk9p6OtFDQnKF5OxwbAgip42CD75r/q
+p421maEDDvvRFR4D+99JZxgAYDBGqRRceUoe16qDzbMvlz0A9paCZFclxeftAxv6
+QlR5rItMz/XdzpBJUpYhdzM0gCzAzdQuVO5tjJxmXhkSMcDP+8Q+Uv6FA9k2VpUV
+E/O5jgpqUJJ2Hc/5rs9VkAPXeA==
+-----END CERTIFICATE-----
+-----BEGIN CERTIFICATE-----
+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
+0Ws=
+-----END CERTIFICATE-----
+-----BEGIN CERTIFICATE-----
+MIICrjCCAjSgAwIBAgIRAPAlEk8VJPmEzVRRaWvTh2AwCgYIKoZIzj0EAwMwgZYx
+CzAJBgNVBAYTAlVTMSIwIAYDVQQKDBlBbWF6b24gV2ViIFNlcnZpY2VzLCBJbmMu
+MRMwEQYDVQQLDApBbWF6b24gUkRTMQswCQYDVQQIDAJXQTEvMC0GA1UEAwwmQW1h
+em9uIFJEUyB1cy1lYXN0LTEgUm9vdCBDQSBFQ0MzODQgRzExEDAOBgNVBAcMB1Nl
+YXR0bGUwIBcNMjEwNTI1MjI0MTU1WhgPMjEyMTA1MjUyMzQxNTVaMIGWMQswCQYD
+VQQGEwJVUzEiMCAGA1UECgwZQW1hem9uIFdlYiBTZXJ2aWNlcywgSW5jLjETMBEG
+A1UECwwKQW1hem9uIFJEUzELMAkGA1UECAwCV0ExLzAtBgNVBAMMJkFtYXpvbiBS
+RFMgdXMtZWFzdC0xIFJvb3QgQ0EgRUNDMzg0IEcxMRAwDgYDVQQHDAdTZWF0dGxl
+MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEx5xjrup8II4HOJw15NTnS3H5yMrQGlbj
+EDA5MMGnE9DmHp5dACIxmPXPMe/99nO7wNdl7G71OYPCgEvWm0FhdvVUeTb3LVnV
+BnaXt32Ek7/oxGk1T+Df03C+W0vmuJ+wo0IwQDAPBgNVHRMBAf8EBTADAQH/MB0G
+A1UdDgQWBBTGXmqBWN/1tkSea4pNw0oHrjk2UDAOBgNVHQ8BAf8EBAMCAYYwCgYI
+KoZIzj0EAwMDaAAwZQIxAIqqZWCSrIkZ7zsv/FygtAusW6yvlL935YAWYPVXU30m
+jkMFLM+/RJ9GMvnO8jHfCgIwB+whlkcItzE9CRQ6CsMo/d5cEHDUu/QW6jSIh9BR
+OGh9pTYPVkUbBiKPA7lVVhre
+-----END CERTIFICATE-----
+`.trim();

package/dist/.test/assets/git/declarations/practices/persist-with-rds/best-practice/src/utils/database/withDatabaseContext.ts

@@ -0,0 +1,54 @@
+import {
+  DatabaseConnection,
+  getOneDatabaseConnection,
+} from './getOneDatabaseConnection';
+
+export interface DatabaseContext {
+  dbConnection: DatabaseConnection;
+}
+
+/**
+ * wraps the function to provide a managed database connection to it's context, if one was not already passed in
+ *
+ * note
+ * - manages the database connection it gives to the function by opening it and closing it once the function finishes
+ * - if a database connection was passed in as part of the arguments, it will instead use that one and will not close it once it finishes (useful for transactions)
+ *
+ * example usage:
+ * ```
+ *   const findById = withDatabaseContext(({ id }: { id: string }, context: { dbConnection: DatabaseConnection }) => {
+ *     // do logic with dbConnection
+ *   });
+ *   // ...
+ *   await findById({ id: '821' }, {}); // the context is required, but the dbConnection within it is not
+ *   await findById({ id: '821' }, { dbConnection }); // pass one in to reuse it, e.g. inside a transaction
+ * ```
+ */
+export const withDatabaseContext = <P1, P2 extends DatabaseContext, R>(
+  logic: (input: P1, context: P2) => R | Promise<R>,
+) => {
+  return async (
+    input: P1,
+    context: Omit<P2, 'dbConnection'> & { dbConnection?: DatabaseConnection },
+  ) => {
+    // open the db connection, if one was not given
+    const dbConnection =
+      context.dbConnection ?? (await getOneDatabaseConnection());
+
+    // try and run the logic with db connection
+    try {
+      // as-cast — why types miss: the input context is `Omit<P2,'dbConnection'> &
+      //   { dbConnection? }`; the spread `{ ...context, dbConnection }` re-adds a
+      //   NON-optional dbConnection, but ts cannot prove a spread of a generic
+      //   `Omit<P2,…> & {…}` reconstitutes the exact `P2` (microsoft/TypeScript#35858).
+      // correct type: the value IS `P2` — every P2 key is present (the omit dropped
+      //   only dbConnection, which the spread restores with a concrete connection).
+      // removal path: ts resolves spread-of-generic to the original type
+      //   (microsoft/TypeScript#35858), or the caller passes a fully-typed P2 in.
+      return await logic(input, { ...context, dbConnection } as P2);
+    } finally {
+      // make sure to close the db connection, both when `logic` throws an error or succeeds
+      if (!context.dbConnection) await dbConnection.end();
+    }
+  };
+};

package/dist/.test/assets/git/declarations/practices/persist-with-rds/best-practice/src/utils/database/withDatabaseTransaction.ts

@@ -0,0 +1,35 @@
+import type { DatabaseConnection } from './getOneDatabaseConnection';
+
+/**
+ * .what = wraps a logic fn so it runs inside one db transaction: START TRANSACTION,
+ *         run the logic, COMMIT on success, ROLLBACK + rethrow on failure. the
+ *         transaction rides the injected `context.dbConnection`.
+ * .why = gives any logic atomic semantics — every write commits together, or none
+ *        does — without each op repeating the begin/commit/rollback dance. a partial
+ *        write cannot survive a throw.
+ * .note = the wrapper is ALWAYS async — it awaits the transaction — so its return
+ *         type is `Promise<R>`, NOT `logic`'s `R | Promise<R>`: a caller of a sync
+ *         `logic` sees a Promise back. `R` is already the resolved value, since ts
+ *         infers it from the `Promise<R>` arm of the union. `Promise<Awaited<R>>` is
+ *         wrong here: `await` of an unconstrained `R` types as `R`, which is not
+ *         assignable to `Awaited<R>`, so tsc fails inside this file.
+ */
+export const withDatabaseTransaction = <
+  P,
+  C extends { dbConnection: DatabaseConnection },
+  R,
+>(
+  logic: (input: P, context: C) => R | Promise<R>,
+): ((input: P, context: C) => Promise<R>) => {
+  return async (input: P, context: C) => {
+    await context.dbConnection.query({ sql: 'START TRANSACTION' }); // begin transaction
+    try {
+      const result = await logic(input, context); // run the request
+      await context.dbConnection.query({ sql: 'COMMIT' }); // commit if successful
+      return result;
+    } catch (error) {
+      await context.dbConnection.query({ sql: 'ROLLBACK' }); // rollback if not successful
+      throw error;
+    }
+  };
+};