@juit/pgproxy-client 1.0.0

package/src/client.ts

@@ -0,0 +1,172 @@
+import { Registry, serialize } from '@juit/pgproxy-types'
+
+import { assert } from './assert'
+import { createProvider } from './provider'
+import { PGResult } from './result'
+
+import type { PGConnection, PGProvider } from './provider'
+
+function serializeParams(params: any[]): (string | null)[] {
+  if (params.length == 0) return []
+
+  const result: (string | null)[] = new Array(params.length)
+  for (let i = 0; i < params.length; i ++) {
+    result[i] =
+      params[i] === undefined ? null :
+      params[i] === null ? null :
+      serialize(params[i])
+  }
+
+  return result
+}
+
+/** An interface for an object that can execute queries on a database */
+export interface PGQueryable {
+  /**
+   * Execute a query on the database
+   *
+   * @param text - The SQL query to execute optionally containing placeholders.
+   * @param params - Any parameter replacement for `$x` placeholders.
+   */
+  query<
+    Row extends Record<string, any> = Record<string, any>,
+    Tuple extends readonly any[] = readonly any [],
+  >(text: string, params?: any[]): Promise<PGResult<Row, Tuple>>
+}
+
+/**
+ * An interface for an object that can execute queries _and transactions_
+ * on a database */
+export interface PGTransactionable extends PGQueryable {
+  /** Start a transaction by issuing a `BEGIN` statement */
+  begin(): Promise<this>
+  /** Commit a transaction by issuing a `COMMIT` statement */
+  commit(): Promise<this>
+  /** Cancel a transaction by issuing a `ROLLBACK` statement */
+  rollback(): Promise<this>
+}
+
+
+/** A consumer for a {@link PGTransactionable} connection */
+export type PGConsumer<T> = (connection: PGTransactionable) => T | PromiseLike<T>
+
+/** The PostgreSQL client */
+export interface PGClient extends PGQueryable {
+  /** The {@link @juit/pgproxy-types#Registry} used to parse results from PostgreSQL */
+  readonly registry: Registry
+
+  /**
+   * Execute a _single_ query on the database.
+   *
+   * Invoking the `query` method on a {@link (PGClient:interface)} does NOT guarantee that
+   * the query will be executed on the same connection, therefore things like
+   * _transactions_ will be immediately rolled back after the query.
+   *
+   * @param text - The SQL query to execute optionally containing placeholders.
+   * @param params - Any parameter replacement for `$x` placeholders.
+   */
+  query<
+    Row extends Record<string, any> = Record<string, any>,
+    Tuple extends readonly any[] = readonly any [],
+  >(text: string, params?: any[]): Promise<PGResult<Row, Tuple>>
+
+  /**
+   * Connect to the database to execute a number of different queries.
+   *
+   * The `consumer` will be passed a {@link PGTransactionable} instance backed
+   * by the _same_ connection to the database, therefore transactions can be
+   * safely executed in the context of the consumer function itself.
+   */
+  connect<T>(consumer: PGConsumer<T>): Promise<T>
+
+  /**
+   * Destroy any resource and underlying connection associated with this
+   * instance's {@link PGProvider}.
+   */
+  destroy(): Promise<void>
+}
+
+/** A constructor for {@link (PGClient:interface)} instances */
+export interface PGClientConstructor {
+  new (url?: string | URL): PGClient
+  new (provider: PGProvider<PGConnection>): PGClient
+}
+
+/**
+ * The PostgreSQL client
+ *
+ * @constructor
+ */
+export const PGClient: PGClientConstructor = class PGClientImpl implements PGClient {
+  readonly registry: Registry = new Registry()
+
+  private _provider: PGProvider<PGConnection>
+
+  constructor(url?: string | URL)
+  constructor(provider: PGProvider<PGConnection>)
+  constructor(urlOrProvider?: string | URL | PGProvider<PGConnection>) {
+    urlOrProvider = urlOrProvider || globalThis?.process?.env?.PGURL
+    assert(urlOrProvider, 'No URL to connect to (PGURL environment variable missing?)')
+    if (typeof urlOrProvider === 'string') urlOrProvider = new URL(urlOrProvider, 'psql:///')
+    assert(urlOrProvider, 'Missing URL or provider for client')
+
+    if (urlOrProvider instanceof URL) {
+      if (!(urlOrProvider.username || urlOrProvider.password)) {
+        const username = globalThis?.process?.env?.PGUSER || ''
+        const password = globalThis?.process?.env?.PGPASSWORD || ''
+        urlOrProvider.username = encodeURIComponent(username)
+        urlOrProvider.password = encodeURIComponent(password)
+      }
+    }
+
+    this._provider = urlOrProvider instanceof URL ?
+        createProvider(urlOrProvider) :
+        urlOrProvider
+  }
+
+  async query<
+    Row extends Record<string, any> = Record<string, any>,
+    Tuple extends readonly any[] = readonly any [],
+  >(text: string, params: any[] = []): Promise<PGResult<Row, Tuple>> {
+    const result = await this._provider.query(text, serializeParams(params))
+    return new PGResult<Row, Tuple>(result, this.registry)
+  }
+
+  async connect<T>(consumer: PGConsumer<T>): Promise<T> {
+    const connection = await this._provider.acquire()
+
+    try {
+      const registry = this.registry
+
+      const consumable: PGTransactionable = {
+        async query<
+          Row extends Record<string, any> = Record<string, any>,
+          Tuple extends readonly any[] = readonly any [],
+        >(text: string, params: any[] = []): Promise<PGResult<Row, Tuple>> {
+          const result = await connection.query(text, serializeParams(params))
+          return new PGResult(result, registry)
+        },
+        async begin(): Promise<PGTransactionable> {
+          await this.query('BEGIN')
+          return this
+        },
+        async commit(): Promise<PGTransactionable> {
+          await this.query('COMMIT')
+          return this
+        },
+        async rollback(): Promise<PGTransactionable> {
+          await this.query('ROLLBACK')
+          return this
+        },
+      }
+
+      return await consumer(consumable)
+    } finally {
+      await this._provider.release(connection)
+    }
+  }
+
+  async destroy(): Promise<void> {
+    return await this._provider.destroy()
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './assert'
+export * from './client'
+export * from './provider'
+export * from './result'
+export * from './websocket'

package/src/provider.ts

@@ -0,0 +1,80 @@
+import { assert } from './assert'
+
+
+/* ========================================================================== *
+ * EXPORTED TYPES                                                             *
+ * ========================================================================== */
+
+/** Describes the result of a query from a {@link PGProvider} */
+export interface PGConnectionResult {
+  /** The SQL command that generated this result (`SELECT`, `INSERT`, ...) */
+  command: string
+  /** Number of rows affected by this query (e.g. added rows in `INSERT`) */
+  rowCount: number
+  /** Fields description with `name` (column name) and `oid` (type) */
+  fields: [ name: string, oid: number ][]
+  /** Result rows, as an array of unparsed `string` results from `libpq` */
+  rows: (string | null)[][]
+}
+
+export interface PGConnection {
+  query(text: string, params: (string | null)[]): Promise<PGConnectionResult>
+}
+
+export interface PGProviderConstructor<Connection extends PGConnection> {
+  new (url: URL): PGProvider<Connection>
+}
+
+export interface PGProvider<Connection extends PGConnection> extends PGConnection {
+  acquire(): Promise<Connection>
+  release(connection: Connection): Promise<void>
+  destroy(): Promise<void>
+}
+
+/* ========================================================================== *
+ * ABSTRACT PROVIDER IMPLEMENTATION                                           *
+ * ========================================================================== */
+
+export abstract class AbstractPGProvider<Connection extends PGConnection>
+implements PGProvider<Connection> {
+  abstract acquire(): Promise<Connection>
+  abstract release(connection: PGConnection): Promise<void>
+
+  async query(text: string, params: string[]): Promise<PGConnectionResult> {
+    const connection = await this.acquire()
+    try {
+      return await connection.query(text, params)
+    } finally {
+      await this.release(connection)
+    }
+  }
+
+  async destroy(): Promise<void> {
+    /* Nothing to do here... */
+  }
+}
+
+/* ========================================================================== *
+ * PROVIDERS REGISTRATION                                                     *
+ * ========================================================================== */
+
+/** All known providers, mapped by protocol */
+const providers = new Map<string, PGProviderConstructor<PGConnection>>()
+
+/** Register a provider, associating it with the specified protocol */
+export function registerProvider(
+    protocol: string,
+    constructor: PGProviderConstructor<PGConnection>,
+): void {
+  protocol = `${protocol}:` // URL always has protocol with _colon_
+  assert(! providers.has(protocol), `Connection provider for "${protocol}..." already registered`)
+  providers.set(protocol, constructor)
+  providers.set(protocol, constructor)
+}
+
+/** Create a new {@link PGProvider} instance for the specified URL */
+export function createProvider(url: URL): PGProvider<PGConnection> {
+  const Provider = providers.get(url.protocol)
+  assert(Provider, `No connection provider registered for "${url.protocol}..."`)
+  return new Provider(url)
+}

package/src/result.ts

@@ -0,0 +1,83 @@
+import type { Registry } from '@juit/pgproxy-types'
+import type { PGConnectionResult } from './provider'
+
+/* ========================================================================== *
+ * EXPORTED TYPES                                                             *
+ * ========================================================================== */
+
+/** The result of a database query */
+export interface PGResult<
+  Row extends Record<string, any> = Record<string, any>,
+  Tuple extends readonly any[] = readonly any [],
+> {
+  /** The SQL command that generated this result (`SELECT`, `INSERT`, ...) */
+  command: string
+  /** Result description describing column names and relative OIDs */
+  fields: { name: string, oid: number }[]
+  /**
+   * The number of rows affected by the query.
+   *
+   * This can be the number of lines returned in `rows` (for `SELECT`
+   * statements, for example) or the number of lines _affected_ by the query
+   * (the number of records inserted by an `INSERT` query).
+   */
+  rowCount: number
+  /** The rows returned by the database query, keyed by the column name. */
+  rows: Row[]
+  /** The tuples returned by the database query, keyed by the column index. */
+  tuples: Tuple[]
+}
+
+/** Constructor for {@link (PGResult:interface)} instances */
+export interface PGResultConstructor {
+  new <
+    Row extends Record<string, any> = Record<string, any>,
+    Tuple extends readonly any[] = readonly any [],
+  >(result: PGConnectionResult, registry: Registry): PGResult<Row, Tuple>
+}
+
+/* ========================================================================== *
+ * PGRESULT IMPLEMENTATION                                                    *
+ * ========================================================================== */
+
+/** The result of a database query */
+export const PGResult: PGResultConstructor = class PGResultImpl<
+  Row extends Record<string, any> = Record<string, any>,
+  Tuple extends readonly any[] = readonly any [],
+> implements PGResult<Row, Tuple> {
+  command: string
+  fields: { name: string, oid: number }[]
+  rowCount: number
+  rows: Row[]
+  tuples: Tuple[]
+
+  constructor(result: PGConnectionResult, registry: Registry) {
+    this.rowCount = result.rowCount
+    this.command = result.command
+    this.fields = result.fields.map(([ name, oid ]) => ({ name, oid }))
+
+    const rowCount = result.rows.length
+    const colCount = result.fields.length
+
+    const mappers = result.fields.map(([ name, oid ]) => ([
+      name, registry.getParser(oid),
+    ] as const))
+
+    const rows = this.rows = new Array(rowCount)
+    const tuples = this.tuples = new Array(rowCount)
+
+    for (let row = 0; row < rowCount; row ++) {
+      const tupleData = tuples[row] = new Array(colCount)
+      const rowData = rows[row] = {} as Record<string, any>
+
+      for (let col = 0; col < colCount; col ++) {
+        const [ name, parser ] = mappers[col]!
+        const value = result.rows[row]![col]!
+        tupleData[col] = rowData[name] =
+          value === null ? null :
+          value === undefined ? null :
+          parser(value)
+      }
+    }
+  }
+}

package/src/websocket.ts

@@ -0,0 +1,269 @@
+import { assert } from './assert'
+
+import type { Request, Response } from '@juit/pgproxy-server'
+import type { PGConnection, PGConnectionResult, PGProvider } from './provider'
+
+/* ========================================================================== *
+ * WEBSOCKET TYPES: in order to work with both WHATWG WebSockets and NodeJS's *
+ * "ws" package, let's abstract our _minimal_ requirement for implementation  *
+ * ensuring type compatibility between the two variants.                      *
+ * ========================================================================== */
+
+const pgWebSocketReadyState = {
+  CONNECTING: 0,
+  OPEN: 1,
+  CLOSING: 2,
+  CLOSED: 3,
+} as const
+
+interface PGWebSocketCloseEvent {
+  readonly code: number;
+  readonly reason: string;
+}
+
+interface PGWebSocketMessageEvent {
+  readonly data?: any
+}
+
+interface PGWebSocketErrorEvent {
+  readonly error?: any
+}
+
+export interface PGWebSocket {
+  addEventListener(event: 'close', handler: (event: PGWebSocketCloseEvent) => void): void
+  addEventListener(event: 'error', handler: (event: PGWebSocketErrorEvent) => void): void
+  addEventListener(event: 'message', handler: (event: PGWebSocketMessageEvent) => void): void
+  addEventListener(event: 'open', handler: () => void): void
+  removeEventListener(event: 'close', handler: (event: PGWebSocketCloseEvent) => void): void
+  removeEventListener(event: 'error', handler: (event: PGWebSocketErrorEvent) => void): void
+  removeEventListener(event: 'message', handler: (event: PGWebSocketMessageEvent) => void): void
+  removeEventListener(event: 'open', handler: () => void): void
+
+  readonly readyState: number;
+
+  send(message: string): void
+  close(code?: number, reason?: string): void;
+}
+
+/* ========================================================================== *
+ * INTERNALS                                                                  *
+ * ========================================================================== */
+
+/* Return the specified message or the default one */
+function msg(message: string | null | undefined, defaultMessage: string): string {
+  return message || defaultMessage
+}
+
+/** A request, simply an unwrapped {@link PGConnectionResult} promise */
+class WebSocketRequest {
+  readonly promise: Promise<PGConnectionResult>
+  readonly resolve!: (result: PGConnectionResult) => void
+  readonly reject!: (reason: any) => void
+
+  constructor(public id: string) {
+    this.promise = new Promise((resolve, reject) => Object.defineProperties(this, {
+      resolve: { value: resolve },
+      reject: { value: reject },
+    }))
+  }
+}
+
+/** Connection implementation, wrapping a `WebSocket` */
+class WebSocketConnectionImpl implements WebSocketConnection {
+  /** Open requests to correlate, keyed by their unique request id */
+  private _requests = new Map<string, WebSocketRequest>()
+  /** Our error, set also when the websocket is closed */
+  private _error?: any
+
+  constructor(private _socket: PGWebSocket, private _getRequestId: () => string) {
+    /* On close, set the error to "WebSocket Closed" if none was set before */
+    _socket.addEventListener('close', (event) => {
+      /* Keep the first error we received... */
+      if (! this._error) {
+        const reason = msg(event.reason, 'Unknown Reason')
+        const message = `WebSocket Closed (${event.code}): ${reason}`
+        this._error = new Error(message)
+      }
+
+      /* Reject all open/pending requests */
+      for (const req of this._requests.values()) req.reject(this._error)
+      this._requests.clear()
+    })
+
+    /* On errors, make sure that the websocket is closed */
+    _socket.addEventListener('error', (event) => {
+      if (event.error) this._error = event.error
+      else this._error = new Error('Unknown WebSocket Error')
+
+      /* Reject all open/pending requests */
+      for (const req of this._requests.values()) req.reject(this._error)
+      this._requests.clear()
+
+      /* Make sure that the websocket is closed */
+      this.close()
+    })
+
+    /* On messages, correlate the message with a request and resolve it */
+    _socket.addEventListener('message', (event) => {
+      try {
+        /* Make sure we have a _text_ message (yup, it's JSON) */
+        const data = event.data
+        assert(typeof data === 'string', 'Data not a "string"')
+
+        /* Parse the response */
+        let payload: Response
+        try {
+          payload = JSON.parse(data)
+        } catch (error) {
+          throw new Error('Unable to parse JSON payload')
+        }
+
+        /* Ensure the payload is a proper object */
+        assert(payload && (typeof payload === 'object'), 'JSON payload is not an object')
+
+        /* Correlate the response ID with a previous request */
+        const request = this._requests.get(payload.id)
+        assert(request, `Invalid response ID "${payload.id}"`)
+
+        /* Determine what kind of response we're dealing with */
+        if (payload.statusCode === 200) {
+          this._requests.delete(payload.id)
+          return request.resolve(payload)
+        } else if (payload.statusCode === 400) {
+          this._requests.delete(payload.id)
+          return request.reject(new Error(`${msg(payload.error, 'Unknown error')} (${payload.statusCode})`))
+        } else {
+          throw new Error(`${msg(payload.error, 'Unknown error')} (${payload.statusCode})`)
+        }
+      } catch (error: any) {
+        _socket.close(1003, msg(error.message, 'Uknown error'))
+      }
+    })
+  }
+
+  close(): void {
+    if (this._socket.readyState === pgWebSocketReadyState.CLOSED) return
+    /* coverage ignore if */
+    if (this._socket.readyState === pgWebSocketReadyState.CLOSING) return
+    this._socket.close(1000, 'Normal termination')
+  }
+
+  query(query: string, params: (string | null)[]): Promise<PGConnectionResult> {
+    /* The error is set also when the websocket is closed, soooooo... */
+    if (this._error) return Promise.reject(this._error)
+
+    /* Wrap sending into a promise, both request.promise and send can fail... */
+    return new Promise((resolve, reject) => {
+      /* Get a unique request ID, and prepare our request */
+      const id = this._getRequestId()
+      const request = new WebSocketRequest(id)
+      this._requests.set(id, request)
+
+      /* Handle responses from the request first */
+      request.promise.then(resolve, reject)
+
+      /* Send our message to the server after the request promise is handled */
+      try {
+        this._socket.send(JSON.stringify({ id, query, params } satisfies Request))
+      } catch (error) {
+        reject(error)
+      }
+    })
+  }
+}
+
+/* ========================================================================== *
+ * EXPORTED                                                                   *
+ * ========================================================================== */
+
+/** A connection to the database backed by a `WebSocket` */
+export interface WebSocketConnection extends PGConnection {
+  /** Close this connection and the underlying `WebSocket` */
+  close(): void
+}
+
+/** An abstract provider implementing `connect(...)` via WHATWG WebSockets */
+export abstract class WebSocketProvider implements PGProvider<WebSocketConnection> {
+  private readonly _connections = new Set<WebSocketConnection>()
+
+  abstract query(text: string, params: (string | null)[]): Promise<PGConnectionResult>
+
+  /** Return a unique request identifier to correlate responses */
+  protected abstract _getUniqueRequestId(): string
+
+  /**
+   * Create a new WebSocket.
+   *
+   * This method can be asynchronous and can return a `Promise`. This is
+   * due to the fact that in order to create our authentication token with the
+   * Web Cryptography API, we need to _await_ the resolution of our token.
+   *
+   * This method should call _synchronously_ the {@link WebSocketProvider._connectWebSocket}
+   * as soon as the WebSocket instance is created, in order to handle `open`,
+   * `close`, or `error` events before the event loop has a chance to resolve
+   * the `Promise` asynchronously.
+   */
+  protected abstract _getWebSocket(): Promise<PGWebSocket>
+
+  /**
+   * Handle the initial connection of a WebSocket.
+   *
+   * This method should be called _synchronously_ by {@link WebSocketProvider._getWebSocket} as
+   * soon as the WebSocket instance is created.
+   */
+  protected _connectWebSocket<S extends PGWebSocket>(socket: S): Promise<S> {
+    return new Promise<S>((resolve, reject) => {
+    /* The socket might have already connected (or failed connecting) in the
+         * time it takes for the event loop to resolve our promise... */
+      if (socket.readyState === pgWebSocketReadyState.OPEN) return resolve(socket)
+      if (socket.readyState !== pgWebSocketReadyState.CONNECTING) {
+        return reject(new Error(`Invalid WebSocket ready state ${socket.readyState}`))
+      }
+
+      const onopen = (): void => {
+        removeEventListeners()
+        resolve(socket)
+      }
+
+      const onerror = (event: PGWebSocketErrorEvent): void => {
+        removeEventListeners()
+        if ('error' in event) return reject(event.error)
+        reject(new Error('Uknown error opening WebSocket'))
+      }
+
+      const onclose = (event: PGWebSocketCloseEvent): void => {
+        removeEventListeners()
+        reject(new Error(`Connection closed with code ${event.code}: ${event.reason}`))
+      }
+
+      const removeEventListeners = (): void => {
+        socket.removeEventListener('open', onopen)
+        socket.removeEventListener('error', onerror)
+        socket.removeEventListener('close', onclose)
+      }
+
+      socket.addEventListener('open', onopen)
+      socket.addEventListener('error', onerror)
+      socket.addEventListener('close', onclose)
+    })
+  }
+
+  async acquire(): Promise<WebSocketConnection> {
+    const socket = await this._getWebSocket()
+
+    /* Wrap the WebSocket into a _connection_, register and return it */
+    const connection = new WebSocketConnectionImpl(socket, () => this._getUniqueRequestId())
+    this._connections.add(connection)
+    return connection
+  }
+
+  async release(connection: WebSocketConnection): Promise<void> {
+    this._connections.delete(connection)
+    connection.close()
+  }
+
+  async destroy(): Promise<void> {
+    this._connections.forEach((connection) => connection.close())
+    this._connections.clear()
+  }
+}