@coffre/db 0.14.4 → 0.15.0

package/src/postgres-js/platform.ts

@@ -0,0 +1,60 @@
+// What the driver needs of where it runs, and nothing else: a TCP socket, its
+// TLS upgrade, a few hashes, and a timer. Two modules give it, with exactly
+// these exports: platform.node.ts (Node's own modules) and platform.workerd.ts
+// (`cloudflare:sockets` and WebCrypto). `@coffre/db`'s `#postgres/platform`
+// import picks one where the package runs: workerd, as wrangler and Vite
+// resolve it for a Worker, or Node, the default. The driver imports
+// `#postgres/platform` alone; this file holds the types both satisfy.
+import type { Buffer } from 'node:buffer';
+import type { ConnectionOptions } from 'node:tls';
+
+/**
+ * What the connection speaks Postgres on: a TCP socket, a TLS one, or a
+ * stream the caller made (`socket`, a tunnel's). A Node `Duplex` is one.
+ */
+export interface Socket {
+  /** Node's states for a socket; a stream that has none never says it is open, so no Terminate is written to it. */
+  readonly readyState?: string;
+  on(event: 'data', listener: (chunk: Buffer) => void): unknown;
+  on(event: 'error', listener: (error: Error) => void): unknown;
+  on(event: 'close', listener: (hadError?: boolean) => void): unknown;
+  on(event: 'connect' | 'secureConnect' | 'drain', listener: () => void): unknown;
+  once(event: 'data', listener: (chunk: Buffer) => void): unknown;
+  once(event: 'close', listener: () => void): unknown;
+  removeListener(event: 'data', listener: (chunk: Buffer) => void): unknown;
+  removeListener(event: 'connect', listener: () => void): unknown;
+  removeAllListeners(): unknown;
+  write(data: Uint8Array, callback?: () => void): boolean;
+  /** Write `data`, the last, and close. */
+  end(data: Uint8Array): unknown;
+  destroy(): unknown;
+  setKeepAlive?(enable: boolean, delay: number): unknown;
+}
+
+/** Where a socket connects: a host and port, TLS to follow or not (workerd asks so up front), or a Unix socket's path. */
+export type Address = { readonly host: string; readonly port: number; readonly tls: boolean } | { readonly path: string };
+
+/** The caller's TLS options, as Node's `tls.connect` takes them; workerd reads `servername` alone. */
+export type TlsOptions = Omit<ConnectionOptions, 'socket'>;
+
+/** What `#postgres/platform` exports, from either module. */
+export interface Platform {
+  /** A TCP socket to `to`, connecting: `connected` is called once it is, heard before it starts; or it says `error` and `close`. */
+  tcp(to: Address, connected: () => void): Socket;
+  /** `socket`, now speaking TLS: it says `secureConnect` once the handshake is done. */
+  startTls(socket: Socket, options: TlsOptions): Socket;
+  /** 4 or 6 for an IP address, 0 for a name. */
+  isIP(host: string): number;
+  /** Run `fn` once what is running now is done, before any timer; and cancel it. */
+  setImmediate(fn: () => void): unknown;
+  clearImmediate(handle: unknown): void;
+  /** Milliseconds, monotonic. */
+  now(): number;
+  randomBytes(length: number): Buffer;
+  /** PBKDF2 with HMAC-SHA-256, as SCRAM-SHA-256 salts a password. */
+  pbkdf2(password: string, salt: Buffer, iterations: number, length: number): Promise<Buffer>;
+  hmac(key: Uint8Array, text: string): Promise<Buffer>;
+  sha256(data: Uint8Array): Promise<Buffer>;
+  /** MD5, in hex. */
+  md5(data: string | Uint8Array): Promise<string>;
+}

package/src/postgres-js/platform.workerd.ts

@@ -0,0 +1,225 @@
+// The driver on workerd (platform.ts): TCP through `cloudflare:sockets`,
+// shaped as the Node socket the connection expects, and WebCrypto, whose
+// hashes are all asynchronous. Upstream's `cf/polyfills.js`, as it was.
+import { Buffer } from 'node:buffer';
+import { EventEmitter } from 'node:events';
+
+import type { Address, Platform, Socket } from './platform.ts';
+
+/** A socket of `cloudflare:sockets`, what of it this uses. */
+interface RawSocket {
+  readonly readable: ReadableStream<Uint8Array>;
+  readonly writable: WritableStream<Uint8Array>;
+  readonly closed: Promise<void>;
+  close(): Promise<void>;
+  startTls(options: { servername?: string }): RawSocket;
+}
+
+type Connect = (address: string, options: { secureTransport?: 'starttls' }) => RawSocket;
+
+const v4Seg = '(?:[0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])';
+const v4Str = `(${v4Seg}[.]){3}${v4Seg}`;
+const IPv4Reg = new RegExp(`^${v4Str}$`);
+
+const v6Seg = '(?:[0-9a-fA-F]{1,4})';
+const IPv6Reg = new RegExp(
+  '^(' +
+  `(?:${v6Seg}:){7}(?:${v6Seg}|:)|` +
+  `(?:${v6Seg}:){6}(?:${v4Str}|:${v6Seg}|:)|` +
+  `(?:${v6Seg}:){5}(?::${v4Str}|(:${v6Seg}){1,2}|:)|` +
+  `(?:${v6Seg}:){4}(?:(:${v6Seg}){0,1}:${v4Str}|(:${v6Seg}){1,3}|:)|` +
+  `(?:${v6Seg}:){3}(?:(:${v6Seg}){0,2}:${v4Str}|(:${v6Seg}){1,4}|:)|` +
+  `(?:${v6Seg}:){2}(?:(:${v6Seg}){0,3}:${v4Str}|(:${v6Seg}){1,5}|:)|` +
+  `(?:${v6Seg}:){1}(?:(:${v6Seg}){0,4}:${v4Str}|(:${v6Seg}){1,6}|:)|` +
+  `(?::((?::${v6Seg}){0,5}:${v4Str}|(?::${v6Seg}){1,7}|:))` +
+  ')(%[0-9a-zA-Z-.:]{1,})?$',
+);
+
+/**
+ * A `cloudflare:sockets` socket as an event emitter: `connect` once it can
+ * write, `data` for each chunk read, `error` then `close` when it fails.
+ * With TLS to follow, it reads one chunk alone, the server's answer to the
+ * SSLRequest, so that the reader is free for `startTls`.
+ */
+export class WorkerdSocket extends EventEmitter {
+  readyState = 'open';
+  raw: RawSocket | null = null;
+  /** Destroyed before `connect` made its socket: closed as soon as it has. */
+  destroyed = false;
+  writer: WritableStreamDefaultWriter<Uint8Array> | null = null;
+  reader: ReadableStreamDefaultReader<Uint8Array> | null = null;
+
+  async connect(port: number, host: string, tls: boolean): Promise<void> {
+    try {
+      this.readyState = 'opening';
+      const { connect } = (await import('cloudflare:sockets' as string)) as { connect: Connect };
+      const raw = (this.raw = connect(host + ':' + port, tls ? { secureTransport: 'starttls' } : {}));
+      if (this.destroyed) return this.abort();
+      raw.closed.then(
+        () => {
+          if (this.readyState !== 'upgrade') return this.close();
+          this.readyState = 'open';
+          this.emit('secureConnect');
+        },
+        (error: unknown) => this.error(error),
+      );
+      this.writer = raw.writable.getWriter();
+      this.reader = raw.readable.getReader();
+
+      void (tls ? this.readFirst() : this.read());
+      void this.writer.ready.then(() => {
+        this.readyState = 'open';
+        this.emit('connect');
+      });
+    } catch (error) {
+      this.error(error);
+    }
+  }
+
+  /** Upgraded to TLS, the same emitter: `secureConnect` once the plain socket under it closes. */
+  upgrade(servername: string | undefined): this {
+    this.writer!.releaseLock();
+    this.reader!.releaseLock();
+    this.readyState = 'upgrading';
+    // Upstream's option, which workerd reads as `expectedServerHostname`: the name is not checked here.
+    const raw = (this.raw = this.raw!.startTls({ servername }));
+    raw.closed.then(
+      () => this.close(),
+      (error: unknown) => this.error(error),
+    );
+    this.writer = raw.writable.getWriter();
+    this.reader = raw.readable.getReader();
+    void this.writer.ready.then(() => {
+      void this.read();
+      this.readyState = 'upgrade';
+    });
+    return this;
+  }
+
+  write(data: Uint8Array, callback?: () => void): boolean {
+    this.writer!.write(data).then(callback, (error: unknown) => this.error(error));
+    return true;
+  }
+
+  end(data?: Uint8Array): unknown {
+    return data ? this.write(data, () => void this.raw!.close()) : this.raw!.close();
+  }
+
+  /**
+   * Closed at once, as Node's `destroy`, whatever it is still writing or opening: its writes aborted and its reads
+   * cancelled, so that nothing buffered is sent, then the raw socket closed, which on its own waits until the socket
+   * has opened and every write has gone (workerd's `Socket::close`). Upstream ended it, which waits for a write stuck
+   * under backpressure too (reviews r2 and r3 of #438). Its TCP connection workerd closes with the request, whose I/O
+   * it is: locally, not before (packages/vault/test/workers-socket.test.ts). Before `connect` has made the raw socket,
+   * it is made only to be closed. Says `close` once, a task later, as Node's does.
+   */
+  destroy(): void {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    if (this.raw !== null) this.abort();
+    setTimeout(() => this.close(), 0);
+  }
+
+  /** The raw socket's streams torn down, then the socket closed (`destroy`). */
+  abort(): void {
+    const raw = this.raw!;
+    void (this.writer ?? raw.writable).abort().catch(() => {});
+    void (this.reader ?? raw.readable).cancel().catch(() => {});
+    void raw.close().catch(() => {});
+  }
+
+  async read(): Promise<void> {
+    try {
+      for (;;) {
+        const { done, value } = await this.reader!.read();
+        if (done) return;
+        this.emit('data', Buffer.from(value));
+      }
+    } catch (error) {
+      this.error(error);
+    }
+  }
+
+  /** The server's answer to the SSLRequest; failed, or the socket closed or destroyed first, said as any read's end. */
+  async readFirst(): Promise<void> {
+    try {
+      const { done, value } = await this.reader!.read();
+      if (done) return this.close();
+      this.emit('data', Buffer.from(value));
+    } catch (error) {
+      this.error(error);
+    }
+  }
+
+  close(): void {
+    if (this.readyState === 'closed') return;
+    this.readyState = 'closed';
+    this.emit('close');
+  }
+
+  /** Said once: past `close` (a `destroy`'s, whose aborted streams fail what was under way), nothing more. */
+  error(error: unknown): void {
+    if (this.readyState === 'closed' || this.destroyed) return;
+    this.emit('error', error);
+    this.close();
+  }
+}
+
+export const tcp: Platform['tcp'] = (to: Address, connected: () => void) => {
+  if ('path' in to) throw new Error('a Unix socket cannot be reached from workerd');
+  const socket = new WorkerdSocket();
+  socket.once('connect', connected);
+  void socket.connect(to.port, to.host, to.tls);
+  return socket as Socket;
+};
+
+export const startTls: Platform['startTls'] = (socket, { servername }) => (socket as WorkerdSocket).upgrade(servername) as Socket;
+
+export const isIP: Platform['isIP'] = (host) => (IPv4Reg.test(host) ? 4 : IPv6Reg.test(host) ? 6 : 0);
+
+// A microtask, as upstream's polyfill: once the writes of this turn are buffered, they go together.
+let ids = 1;
+const tasks = new Set<number>();
+
+export const setImmediate: Platform['setImmediate'] = (fn) => {
+  const id = ids++;
+  tasks.add(id);
+  queueMicrotask(() => {
+    if (tasks.has(id)) {
+      fn();
+      tasks.delete(id);
+    }
+  });
+  return id;
+};
+
+export const clearImmediate: Platform['clearImmediate'] = (handle) => {
+  tasks.delete(handle as number);
+};
+
+export const now: Platform['now'] = () => performance.now();
+
+export const randomBytes: Platform['randomBytes'] = (length) => crypto.getRandomValues(Buffer.alloc(length));
+
+const encoder = new TextEncoder();
+
+/** `x`, as WebCrypto types the bytes it takes: a Buffer's memory is never shared. */
+const own = (x: Uint8Array) => x as Uint8Array<ArrayBuffer>;
+
+export const pbkdf2: Platform['pbkdf2'] = async (password, salt, iterations, length) =>
+  Buffer.from(
+    await crypto.subtle.deriveBits(
+      { name: 'PBKDF2', hash: 'SHA-256', salt: own(salt), iterations },
+      await crypto.subtle.importKey('raw', encoder.encode(password), 'PBKDF2', false, ['deriveBits']),
+      length * 8,
+    ),
+  );
+
+export const hmac: Platform['hmac'] = async (key, text) =>
+  Buffer.from(await crypto.subtle.sign('HMAC', await crypto.subtle.importKey('raw', own(key), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']), encoder.encode(text)));
+
+export const sha256: Platform['sha256'] = async (data) => Buffer.from(await crypto.subtle.digest('SHA-256', own(data)));
+
+// workerd's WebCrypto has MD5, which the standard leaves out.
+export const md5: Platform['md5'] = async (data) =>
+  Buffer.from(await crypto.subtle.digest('MD5', typeof data === 'string' ? encoder.encode(data) : own(data))).toString('hex');

package/src/postgres-js/query.ts

@@ -0,0 +1,123 @@
+import type { RowList } from './index.ts';
+import type { Column } from './result.ts';
+
+/** A statement as sent: its text, its parameters' types (0 for the server to say), and its columns once described. */
+export interface Statement {
+  string: string;
+  types: number[];
+  /** Once described: by a RowDescription, or NoData's none. */
+  columns: Column[] | null;
+}
+
+export interface QueryOptions {
+  /** Sent with the simple protocol, one Query message: what a statement with no parameters is, by default. */
+  simple: boolean;
+}
+
+/**
+ * One statement of a group (`group`, index.ts): its text and values, whether
+ * its rows come as arrays, and what the connection works out as it sends it.
+ */
+export interface Member {
+  text: string;
+  args: unknown[];
+  arrays: boolean;
+  parameters: unknown[];
+  statement: Statement | null;
+}
+
+/**
+ * A statement, sent once awaited (`then`, `catch`, `finally`) or `execute`d,
+ * a task later, through the pool or the transaction that made it: its
+ * `handler`. A promise of its result, its rows as objects or, after
+ * `values()`, as arrays.
+ */
+export class Query<T = unknown> extends Promise<T> {
+  readonly text: string;
+  readonly args: unknown[];
+  readonly options: QueryOptions;
+  readonly #handler: (query: Query) => void;
+  /** Where it was made, when the client debugs. */
+  readonly #origin: Error | null;
+  /** Its rows as arrays of values rather than objects. */
+  arrays = false;
+  executed = false;
+
+  // What the connection works out as it sends it.
+  parameters: unknown[] = [];
+  statement: Statement | null = null;
+  /** Whether its parameters' types are asked of the server before its values go (`typedByServer`, connection.ts). */
+  describeFirst = false;
+  /** A transaction's first statement: its BEGIN, sent ahead of it under its Sync (`begin`, index.ts); and whether it took. */
+  begin: string | null = null;
+  began = false;
+  /**
+   * Coffre: a group's statements, sent under one Sync and answered together, each its own result (`group`, index.ts),
+   * and the one answering now. Null for a statement of its own.
+   */
+  group: Member[] | null = null;
+  member = 0;
+
+  readonly resolve: (value: unknown) => void;
+  readonly reject: (error: unknown) => void;
+
+  constructor(text: string, args: unknown[], handler: (query: Query) => void, options: QueryOptions, debug: boolean) {
+    let resolve!: (value: T) => void;
+    let reject!: (error: unknown) => void;
+    super((a, b) => {
+      resolve = a;
+      reject = b;
+    });
+    this.text = text;
+    this.args = args;
+    this.options = options;
+    this.#handler = handler;
+    this.#origin = debug ? new Error() : null;
+    this.resolve = resolve as (value: unknown) => void;
+    this.reject = reject;
+  }
+
+  /** Where it was made, for its error's stack: nothing unless the client debugs. */
+  get origin(): string {
+    return this.#origin?.stack ?? '';
+  }
+
+  /** What `then` and the like make: a plain promise, not another statement. */
+  static get [Symbol.species](): PromiseConstructor {
+    return Promise;
+  }
+
+  values(): Query<RowList<unknown[][]>> {
+    this.arrays = true;
+    return this as never;
+  }
+
+  execute(): this {
+    void this.#handle();
+    return this;
+  }
+
+  // `any` for what it fails with, as Promise's own `then` and `catch` take it.
+  override then<A = T, B = never>(onfulfilled?: ((value: T) => A | PromiseLike<A>) | null, onrejected?: ((reason: any) => B | PromiseLike<B>) | null): Promise<A | B> {
+    void this.#handle();
+    return super.then(onfulfilled, onrejected);
+  }
+
+  override catch<B = never>(onrejected?: ((reason: any) => B | PromiseLike<B>) | null): Promise<T | B> {
+    void this.#handle();
+    return super.catch(onrejected);
+  }
+
+  override finally(onfinally?: (() => void) | null): Promise<T> {
+    void this.#handle();
+    return super.finally(onfinally);
+  }
+
+  /** Sent once, a task after it is first asked for. */
+  async #handle(): Promise<void> {
+    if (this.executed) return;
+    this.executed = true;
+    await null;
+    this.#handler(this);
+  }
+}

package/src/postgres-js/queue.ts

@@ -0,0 +1,42 @@
+/** A queue that takes from either end, and lets go of what it took. */
+export class Queue<T> {
+  #xs: (T | undefined)[] = [];
+  #index = 0;
+
+  get length(): number {
+    return this.#xs.length - this.#index;
+  }
+
+  push(x: T): T {
+    this.#xs.push(x);
+    return x;
+  }
+
+  remove(x: T): T | null {
+    const index = this.#xs.indexOf(x);
+    if (index === -1) return null;
+    this.#xs.splice(index, 1);
+    return x;
+  }
+
+  // Coffre: the newest, for the pool to take the connection idle the shortest, as pg-pool does: the others stay
+  // idle, and close once idle_timeout passes, and the backends used stay few and warm.
+  pop(): T | undefined {
+    if (this.#xs.length === this.#index) return undefined;
+    const out = this.#xs.pop();
+    if (this.#index === this.#xs.length) this.#clear();
+    return out;
+  }
+
+  shift(): T | undefined {
+    const out = this.#xs[this.#index++];
+    if (this.#index === this.#xs.length) this.#clear();
+    else this.#xs[this.#index - 1] = undefined;
+    return out;
+  }
+
+  #clear(): void {
+    this.#index = 0;
+    this.#xs = [];
+  }
+}

package/src/postgres-js/result.ts

@@ -0,0 +1,46 @@
+import type { Statement } from './query.ts';
+
+/** A backend's process id and secret key, as BackendKeyData gave them: what a CancelRequest names. */
+export interface Backend {
+  pid: number | null;
+  secret: number | null;
+}
+
+/** What Postgres said of a column, in a RowDescription. */
+export interface Column {
+  name: string;
+  /** How its text is read, by its type; as text when there is none. */
+  parser: ((text: string) => unknown) | undefined;
+  table: number;
+  number: number;
+  type: number;
+}
+
+/**
+ * A statement's rows, with what its CommandComplete said beside them: `count`
+ * (rows inserted, updated, deleted or returned), `command`, and `state`, the
+ * backend that ran it. Not enumerable, so that a result spreads as its rows.
+ */
+export class Result extends Array<unknown> {
+  declare count: number | null;
+  declare state: Backend | null;
+  declare command: string | null;
+  declare columns: Column[] | null;
+  declare statement: Statement | null;
+
+  constructor() {
+    super();
+    Object.defineProperties(this, {
+      count: { value: null, writable: true },
+      state: { value: null, writable: true },
+      command: { value: null, writable: true },
+      columns: { value: null, writable: true },
+      statement: { value: null, writable: true },
+    });
+  }
+
+  /** What `map`, `filter` and the like make: a plain array. */
+  static get [Symbol.species](): ArrayConstructor {
+    return Array;
+  }
+}

package/src/postgres-js/types.ts

@@ -0,0 +1,52 @@
+import { Buffer } from 'node:buffer';
+
+/** How a column's text is read, by its type's oid. */
+export type Parsers = Record<number, ((text: string) => unknown) | undefined>;
+/** How a value is written as text, by its parameter's type's oid. */
+export type Serializers = Record<number, ((value: unknown) => unknown) | undefined>;
+
+/**
+ * The types read and written by default, as upstream's `types.js`: each one's
+ * oid when sent (`to`), the oids read as it (`from`), and how.
+ */
+const TYPES: { to: number; from: number[]; serialize: (x: unknown) => string; parse?: (x: string) => unknown }[] = [
+  // string: read as the text it is.
+  { to: 25, from: [], serialize: (x) => String(x) },
+  // number
+  { to: 0, from: [21, 23, 26, 700, 701], serialize: (x) => String(x), parse: (x) => +x },
+  // json
+  { to: 114, from: [114, 3802], serialize: (x) => JSON.stringify(x), parse: (x) => JSON.parse(x) as unknown },
+  // boolean
+  { to: 16, from: [16], serialize: (x) => (x === true ? 't' : 'f'), parse: (x) => x === 't' },
+  // date
+  { to: 1184, from: [1082, 1114, 1184], serialize: (x) => (x instanceof Date ? x : new Date(x as string)).toISOString(), parse: (x) => new Date(x) },
+  // bytea
+  { to: 17, from: [17], serialize: (x) => '\\x' + Buffer.from(x as Uint8Array).toString('hex'), parse: (x) => Buffer.from(x.slice(2), 'hex') },
+];
+
+/** A client's own parsers and serializers, made from the defaults: it may change them (`options.parsers[oid] = …`). */
+export function defaultTypes(): { parsers: Parsers; serializers: Serializers } {
+  const parsers: Parsers = {};
+  const serializers: Serializers = {};
+  for (const type of TYPES) {
+    for (const oid of type.from) parsers[oid] = type.parse;
+    serializers[type.to] = type.serialize;
+    for (const oid of type.from) serializers[oid] = type.serialize;
+  }
+  return { parsers, serializers };
+}
+
+/**
+ * The type a value is sent as, which a parameter's serializer goes by: 0,
+ * none, for the server to type its text, but for a date, bytes, a boolean or
+ * a bigint. An array goes by its first element (porsager/postgres#1225; coffre
+ * sends arrays as their text, `asPgSends` in postgres.ts).
+ */
+export function inferType(x: unknown): number {
+  return x instanceof Date ? 1184
+    : x instanceof Uint8Array ? 17
+    : x === true || x === false ? 16
+    : typeof x === 'bigint' ? 20
+    : Array.isArray(x) ? inferType(x[0])
+    : 0;
+}