@strav/cache 1.0.0-alpha.25

package/src/drivers/memcached/memcached_client.ts

@@ -0,0 +1,251 @@
+/**
+ * Minimal Memcached text-protocol client over `Bun.connect`.
+ *
+ * Just enough surface to back `MemcachedCache`: `set` / `add` / `get`
+ * / `delete` / `incr` / `decr` / `flush_all`. No SASL auth, no
+ * pipelining, no consistent-hash routing — one TCP connection to one
+ * server, serialized request stream.
+ *
+ * Requests are queued; the next request waits for the previous
+ * response to land so the parser stays simple (response bytes can
+ * only be matched against the head of the queue). Throughput at one
+ * server is fine for cache workloads; if you outgrow it, an app
+ * builds its own multi-conn wrapper or uses Redis.
+ *
+ * Bytes go through `TextEncoder` / `TextDecoder` — Memcached's text
+ * protocol is single-byte ASCII for control lines but values are
+ * binary-safe. The driver `JSON.stringify`s on the way in and is
+ * tolerant of non-JSON strings on the way out (counters return
+ * decimal strings).
+ */
+
+const ENCODER = new TextEncoder()
+const DECODER = new TextDecoder()
+
+export interface MemcachedClientOptions {
+  host: string
+  port: number
+  /** Connection timeout in ms. Default `5000`. */
+  connectTimeoutMs?: number
+  /** Per-request response timeout in ms. Default `5000`. */
+  requestTimeoutMs?: number
+}
+
+interface PendingRequest {
+  // Lines we've collected so far (excluding the terminator).
+  buffer: Uint8Array
+  resolve: (response: Uint8Array) => void
+  reject: (err: Error) => void
+  timer: ReturnType<typeof setTimeout> | undefined
+}
+
+type Socket = Awaited<ReturnType<typeof Bun.connect>>
+
+export class MemcachedClient {
+  private readonly host: string
+  private readonly port: number
+  private readonly connectTimeoutMs: number
+  private readonly requestTimeoutMs: number
+
+  private socket: Socket | undefined
+  private connecting: Promise<Socket> | undefined
+  private closed = false
+
+  /** FIFO queue of (request → pending response). */
+  private readonly queue: PendingRequest[] = []
+
+  constructor(options: MemcachedClientOptions) {
+    this.host = options.host
+    this.port = options.port
+    this.connectTimeoutMs = options.connectTimeoutMs ?? 5_000
+    this.requestTimeoutMs = options.requestTimeoutMs ?? 5_000
+  }
+
+  async send(command: string | Uint8Array): Promise<Uint8Array> {
+    if (this.closed) throw new Error('MemcachedClient: closed.')
+    const socket = await this.connect()
+    return new Promise<Uint8Array>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        // Pull this request from the queue when it times out so the
+        // parser doesn't fire callbacks on a dead promise. Subsequent
+        // responses still land on the next pending request.
+        const idx = this.queue.findIndex((r) => r === pending)
+        if (idx >= 0) this.queue.splice(idx, 1)
+        reject(new Error(`MemcachedClient: request timed out after ${this.requestTimeoutMs}ms.`))
+      }, this.requestTimeoutMs)
+      const pending: PendingRequest = {
+        buffer: new Uint8Array(0),
+        resolve,
+        reject,
+        timer,
+      }
+      this.queue.push(pending)
+      const payload = typeof command === 'string' ? ENCODER.encode(command) : command
+      socket.write(payload)
+    })
+  }
+
+  async close(): Promise<void> {
+    this.closed = true
+    for (const p of this.queue) {
+      if (p.timer !== undefined) clearTimeout(p.timer)
+      p.reject(new Error('MemcachedClient: closed.'))
+    }
+    this.queue.length = 0
+    if (this.socket !== undefined) {
+      try {
+        this.socket.end()
+      } catch {
+        // Already torn down.
+      }
+      this.socket = undefined
+    }
+  }
+
+  // ─── Internals ─────────────────────────────────────────────────────────────
+
+  private async connect(): Promise<Socket> {
+    if (this.socket !== undefined) return this.socket
+    if (this.connecting !== undefined) return this.connecting
+    this.connecting = this.openSocket()
+    try {
+      this.socket = await this.connecting
+      return this.socket
+    } finally {
+      this.connecting = undefined
+    }
+  }
+
+  private async openSocket(): Promise<Socket> {
+    let resolveOpen: ((socket: Socket) => void) | undefined
+    let rejectOpen: ((err: Error) => void) | undefined
+    const opened = new Promise<Socket>((res, rej) => {
+      resolveOpen = res
+      rejectOpen = rej
+    })
+    const timeout = setTimeout(() => {
+      rejectOpen?.(
+        new Error(`MemcachedClient: connect timed out after ${this.connectTimeoutMs}ms.`),
+      )
+    }, this.connectTimeoutMs)
+
+    const sock = await Bun.connect({
+      hostname: this.host,
+      port: this.port,
+      socket: {
+        open: (socket) => {
+          clearTimeout(timeout)
+          resolveOpen?.(socket as Socket)
+        },
+        data: (_socket, chunk) => {
+          // Bun typings model the chunk as Buffer; downstream code
+          // uses Uint8Array operations only, so the cast is safe.
+          this.onData(new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength))
+        },
+        error: (_socket, err) => {
+          this.failQueue(err)
+        },
+        close: () => {
+          this.failQueue(new Error('MemcachedClient: socket closed.'))
+          this.socket = undefined
+        },
+      },
+    })
+    return opened.catch((err) => {
+      try {
+        sock.end()
+      } catch {
+        // ignore
+      }
+      throw err
+    })
+  }
+
+  /**
+   * Append chunk to the head-of-queue request and check whether the
+   * accumulated buffer now represents a complete reply. Replies end on
+   * one of the protocol's terminator lines:
+   *
+   *   - `END\r\n` (after a `get` / `gets` block)
+   *   - `STORED\r\n` / `NOT_STORED\r\n` / `EXISTS\r\n` (storage commands)
+   *   - `DELETED\r\n` / `NOT_FOUND\r\n` / `TOUCHED\r\n`
+   *   - `OK\r\n` (flush_all, version)
+   *   - a single decimal line (incr/decr — `12345\r\n`)
+   *   - `CLIENT_ERROR <msg>\r\n` / `SERVER_ERROR <msg>\r\n` / `ERROR\r\n`
+   */
+  private onData(chunk: Uint8Array): void {
+    while (chunk.length > 0) {
+      const pending = this.queue[0]
+      if (pending === undefined) {
+        // Stray bytes after a queue purge — drop them.
+        return
+      }
+      const merged = new Uint8Array(pending.buffer.length + chunk.length)
+      merged.set(pending.buffer)
+      merged.set(chunk, pending.buffer.length)
+      pending.buffer = merged
+      const text = DECODER.decode(pending.buffer)
+      const end = findReplyEnd(text)
+      if (end === -1) {
+        // Need more bytes — exit and wait.
+        return
+      }
+      const replyText = text.slice(0, end)
+      const replyBytes = ENCODER.encode(replyText)
+      const leftoverText = text.slice(end)
+      this.queue.shift()
+      if (pending.timer !== undefined) clearTimeout(pending.timer)
+      pending.resolve(replyBytes)
+      chunk = ENCODER.encode(leftoverText)
+    }
+  }
+
+  private failQueue(err: Error): void {
+    for (const p of this.queue) {
+      if (p.timer !== undefined) clearTimeout(p.timer)
+      p.reject(err)
+    }
+    this.queue.length = 0
+  }
+}
+
+/**
+ * Locate the end-of-reply boundary in the text-form accumulated buffer.
+ * Returns the index *after* the terminator. `-1` if the reply is
+ * incomplete.
+ */
+function findReplyEnd(text: string): number {
+  // Multi-line `get` reply ends with `END\r\n` on its own line. Scan
+  // for that first — the response may have any number of `VALUE` /
+  // data lines before it.
+  const endMarker = '\r\nEND\r\n'
+  const endIdx = text.indexOf(endMarker)
+  if (endIdx >= 0) return endIdx + endMarker.length
+
+  // Replies that ARE just `END\r\n` (empty get) — the buffer starts
+  // with it.
+  if (text.startsWith('END\r\n')) return 'END\r\n'.length
+
+  // Single-line replies — find the first CRLF and check the line.
+  const firstCrlf = text.indexOf('\r\n')
+  if (firstCrlf === -1) return -1
+  const firstLine = text.slice(0, firstCrlf)
+  if (SINGLE_LINE_REPLIES.has(firstLine)) return firstCrlf + 2
+  if (firstLine.startsWith('CLIENT_ERROR ')) return firstCrlf + 2
+  if (firstLine.startsWith('SERVER_ERROR ')) return firstCrlf + 2
+  if (firstLine.startsWith('VERSION ')) return firstCrlf + 2
+  // incr/decr return a bare decimal value.
+  if (/^\d+$/.test(firstLine)) return firstCrlf + 2
+  return -1
+}
+
+const SINGLE_LINE_REPLIES = new Set([
+  'STORED',
+  'NOT_STORED',
+  'EXISTS',
+  'DELETED',
+  'NOT_FOUND',
+  'TOUCHED',
+  'OK',
+  'ERROR',
+])

package/src/drivers/memory/index.ts

@@ -0,0 +1 @@
+export { MemoryCache, type MemoryCacheOptions } from './memory_cache.ts'

package/src/drivers/memory/memory_cache.ts

@@ -0,0 +1,279 @@
+/**
+ * `MemoryCache` — in-process cache backed by a single `Map`.
+ *
+ * Right driver for: dev, tests, per-process caches that don't need
+ * cross-process visibility. Wrong driver for: production deployments
+ * with more than one node (each node sees its own copy).
+ *
+ * Atomic ops (`add`, `increment`, `decrement`) are atomic *within
+ * this process* — Bun's event loop is single-threaded so no JS-level
+ * race exists. Cross-process, you want `PostgresCache`.
+ *
+ * Locks + tags are first-class here for parity with the Postgres
+ * driver, but the lock guarantee is only meaningful in a single
+ * process (use Postgres for cross-process mutual exclusion). The tag
+ * implementation walks two parallel maps (`key → tag-set`,
+ * `tag → key-set`) — cheap because everything is in memory.
+ */
+
+import { ulid } from '@strav/kernel'
+import { Cache } from '../../cache.ts'
+import { CacheLockTimeoutError } from '../../cache_error.ts'
+import { ttlToExpiresAt } from '../../ttl.ts'
+import type { CacheEntry, CacheLock, CacheTtl, TaggedCache } from '../../types.ts'
+
+export interface MemoryCacheOptions {
+  /**
+   * Override the clock for deterministic TTL tests. Default `Date.now`.
+   */
+  now?: () => number
+}
+
+export class MemoryCache extends Cache {
+  private readonly entries = new Map<string, CacheEntry<unknown>>()
+  private readonly keyTags = new Map<string, Set<string>>()
+  private readonly tagKeys = new Map<string, Set<string>>()
+  private readonly locks = new Map<string, { owner: string; expiresAt: number }>()
+  private readonly nowFn: () => number
+
+  constructor(options: MemoryCacheOptions = {}) {
+    super()
+    this.nowFn = options.now ?? Date.now
+  }
+
+  override async get<T = unknown>(key: string, fallback: T | null = null): Promise<T | null> {
+    const entry = this.entries.get(key)
+    if (entry === undefined) return fallback
+    if (this.expired(entry)) {
+      this.entries.delete(key)
+      this.removeKeyFromAllTags(key)
+      return fallback
+    }
+    return entry.value as T
+  }
+
+  override async put(key: string, value: unknown, ttl?: CacheTtl): Promise<void> {
+    this.entries.set(key, { value, expiresAt: ttlToExpiresAt(ttl, this.nowFn()) })
+  }
+
+  override async has(key: string): Promise<boolean> {
+    const entry = this.entries.get(key)
+    if (entry === undefined) return false
+    if (this.expired(entry)) {
+      this.entries.delete(key)
+      this.removeKeyFromAllTags(key)
+      return false
+    }
+    return true
+  }
+
+  override async forget(key: string): Promise<boolean> {
+    this.removeKeyFromAllTags(key)
+    return this.entries.delete(key)
+  }
+
+  override async flush(): Promise<void> {
+    this.entries.clear()
+    this.keyTags.clear()
+    this.tagKeys.clear()
+    // Active locks aren't cleared — they're a separate concept from
+    // cached values, and `flush()` shouldn't surprise a holder by
+    // dropping their lock.
+  }
+
+  override async add(key: string, value: unknown, ttl: CacheTtl): Promise<boolean> {
+    const existing = this.entries.get(key)
+    if (existing !== undefined && !this.expired(existing)) return false
+    this.entries.set(key, { value, expiresAt: ttlToExpiresAt(ttl, this.nowFn()) })
+    return true
+  }
+
+  override async increment(key: string, by = 1): Promise<number> {
+    return this.adjust(key, by)
+  }
+
+  override async decrement(key: string, by = 1): Promise<number> {
+    return this.adjust(key, -by)
+  }
+
+  override lock(name: string, ttl: CacheTtl): CacheLock {
+    return new MemoryCacheLock(this, name, ttl)
+  }
+
+  override tags(...tags: string[]): TaggedCache {
+    return new MemoryTaggedCache(this, tags)
+  }
+
+  // ─── Diagnostics / helpers ─────────────────────────────────────────────────
+
+  /** Total entry count, including expired-but-not-yet-evicted rows. */
+  size(): number {
+    return this.entries.size
+  }
+
+  // ─── Driver-internals exposed to the lock + tagged wrappers ────────────────
+
+  /** @internal */
+  _now(): number {
+    return this.nowFn()
+  }
+
+  /** @internal */
+  _tryAcquireLock(name: string, ttl: CacheTtl): string | undefined {
+    const current = this.locks.get(name)
+    if (current !== undefined && current.expiresAt > this.nowFn()) return undefined
+    const owner = ulid()
+    this.locks.set(name, { owner, expiresAt: ttlToExpiresAt(ttl, this.nowFn()) ?? Infinity })
+    return owner
+  }
+
+  /** @internal */
+  _releaseLock(name: string, owner: string): boolean {
+    const current = this.locks.get(name)
+    if (current === undefined) return false
+    if (current.owner !== owner) return false
+    this.locks.delete(name)
+    return true
+  }
+
+  /** @internal */
+  _putWithTags(key: string, value: unknown, ttl: CacheTtl, tags: readonly string[]): void {
+    this.entries.set(key, { value, expiresAt: ttlToExpiresAt(ttl, this.nowFn()) })
+    this.setKeyTags(key, tags)
+  }
+
+  /** @internal */
+  _flushTags(tags: readonly string[]): number {
+    const toDrop = new Set<string>()
+    for (const tag of tags) {
+      const keys = this.tagKeys.get(tag)
+      if (keys === undefined) continue
+      for (const k of keys) toDrop.add(k)
+    }
+    for (const k of toDrop) {
+      this.entries.delete(k)
+      this.removeKeyFromAllTags(k)
+    }
+    return toDrop.size
+  }
+
+  private adjust(key: string, delta: number): number {
+    const entry = this.entries.get(key)
+    if (entry === undefined || this.expired(entry)) {
+      this.entries.set(key, { value: delta, expiresAt: null })
+      return delta
+    }
+    const current = typeof entry.value === 'number' ? entry.value : Number(entry.value)
+    const next = current + delta
+    entry.value = next
+    return next
+  }
+
+  private setKeyTags(key: string, tags: readonly string[]): void {
+    // Reset existing tag wiring for this key first — same key getting
+    // re-tagged is a legit operation, and stale tag links would
+    // make `flushTags` over-delete.
+    this.removeKeyFromAllTags(key)
+    const tagSet = new Set(tags)
+    this.keyTags.set(key, tagSet)
+    for (const tag of tagSet) {
+      let bucket = this.tagKeys.get(tag)
+      if (bucket === undefined) {
+        bucket = new Set()
+        this.tagKeys.set(tag, bucket)
+      }
+      bucket.add(key)
+    }
+  }
+
+  private removeKeyFromAllTags(key: string): void {
+    const tagSet = this.keyTags.get(key)
+    if (tagSet === undefined) return
+    for (const tag of tagSet) {
+      const bucket = this.tagKeys.get(tag)
+      if (bucket === undefined) continue
+      bucket.delete(key)
+      if (bucket.size === 0) this.tagKeys.delete(tag)
+    }
+    this.keyTags.delete(key)
+  }
+
+  private expired(entry: CacheEntry<unknown>): boolean {
+    return entry.expiresAt !== null && entry.expiresAt <= this.nowFn()
+  }
+}
+
+class MemoryCacheLock implements CacheLock {
+  private owner: string | undefined
+
+  constructor(
+    private readonly cache: MemoryCache,
+    readonly name: string,
+    private readonly ttl: CacheTtl,
+  ) {}
+
+  async acquire(): Promise<boolean> {
+    if (this.owner !== undefined) return false
+    const token = this.cache._tryAcquireLock(this.name, this.ttl)
+    if (token === undefined) return false
+    this.owner = token
+    return true
+  }
+
+  async release(): Promise<boolean> {
+    if (this.owner === undefined) return false
+    const released = this.cache._releaseLock(this.name, this.owner)
+    this.owner = undefined
+    return released
+  }
+
+  async block<T>(timeoutMs: number, fn: () => Promise<T> | T): Promise<T> {
+    // parseTtl validates the input even though we don't use seconds here.
+    if (timeoutMs < 0 || !Number.isFinite(timeoutMs)) {
+      throw new Error(
+        `CacheLock.block: timeoutMs must be a non-negative finite number; got: ${timeoutMs}`,
+      )
+    }
+    const deadline = this.cache._now() + timeoutMs
+    const pollIntervalMs = 50
+    while (true) {
+      if (await this.acquire()) {
+        try {
+          return await fn()
+        } finally {
+          await this.release()
+        }
+      }
+      if (this.cache._now() >= deadline) {
+        throw new CacheLockTimeoutError(
+          `CacheLock "${this.name}" not acquired within ${timeoutMs}ms.`,
+          { context: { lock: this.name, timeoutMs } },
+        )
+      }
+      await new Promise<void>((r) => setTimeout(r, pollIntervalMs))
+    }
+  }
+}
+
+class MemoryTaggedCache implements TaggedCache {
+  constructor(
+    private readonly cache: MemoryCache,
+    readonly tags: readonly string[],
+  ) {}
+
+  async put(key: string, value: unknown, ttl?: CacheTtl): Promise<void> {
+    this.cache._putWithTags(key, value, ttl, this.tags)
+  }
+
+  get<T = unknown>(key: string, fallback: T | null = null): Promise<T | null> {
+    return this.cache.get<T>(key, fallback)
+  }
+
+  forget(key: string): Promise<boolean> {
+    return this.cache.forget(key)
+  }
+
+  async flush(): Promise<number> {
+    return this.cache._flushTags(this.tags)
+  }
+}

package/src/drivers/postgres/apply_cache_migration.ts

@@ -0,0 +1,54 @@
+/**
+ * `applyCacheMigration` — emit DDL for the three tables `PostgresCache`
+ * uses.
+ *
+ *   - `strav_cache (key text PK, data jsonb, expires_at timestamptz NULL)`
+ *     — the main key/value store. `expires_at` indexed for the
+ *     periodic sweep.
+ *   - `strav_cache_locks (name text PK, owner text NOT NULL,
+ *     expires_at timestamptz NOT NULL)` — distributed-lock slots.
+ *   - `strav_cache_tags (key text NOT NULL, tag text NOT NULL,
+ *     PRIMARY KEY (key, tag))` — tag-to-key index. `tag` indexed
+ *     for the flush path. FK to `strav_cache.key` ON DELETE CASCADE
+ *     so cache-entry deletion takes its tag wiring with it.
+ *
+ * Schemas are NOT registered with the SchemaRegistry because the cache
+ * table layout (text PK, composite PK on tags) doesn't fit the schema
+ * DSL — apps just invoke this helper from a migration `up()` and DROP
+ * the tables in `down()`.
+ */
+
+import type { DatabaseExecutor } from '@strav/database'
+
+export async function applyCacheMigration(db: DatabaseExecutor): Promise<void> {
+  await db.execute(
+    `CREATE TABLE IF NOT EXISTS "strav_cache" (
+       "key" text PRIMARY KEY,
+       "data" jsonb NOT NULL,
+       "expires_at" timestamptz NULL
+     )`,
+  )
+  await db.execute(
+    `CREATE INDEX IF NOT EXISTS "idx_strav_cache_expires_at"
+     ON "strav_cache" ("expires_at")
+     WHERE "expires_at" IS NOT NULL`,
+  )
+  await db.execute(
+    `CREATE TABLE IF NOT EXISTS "strav_cache_locks" (
+       "name" text PRIMARY KEY,
+       "owner" text NOT NULL,
+       "expires_at" timestamptz NOT NULL
+     )`,
+  )
+  await db.execute(
+    `CREATE TABLE IF NOT EXISTS "strav_cache_tags" (
+       "key" text NOT NULL,
+       "tag" text NOT NULL,
+       PRIMARY KEY ("key", "tag"),
+       FOREIGN KEY ("key") REFERENCES "strav_cache" ("key") ON DELETE CASCADE
+     )`,
+  )
+  await db.execute(
+    `CREATE INDEX IF NOT EXISTS "idx_strav_cache_tags_tag" ON "strav_cache_tags" ("tag")`,
+  )
+}

package/src/drivers/postgres/index.ts

@@ -0,0 +1,10 @@
+export { applyCacheMigration } from './apply_cache_migration.ts'
+export {
+  PostgresCache,
+  type PostgresCacheDatabase,
+  type PostgresCacheOptions,
+} from './postgres_cache.ts'
+export {
+  type PostgresCacheConfig,
+  PostgresCacheProvider,
+} from './postgres_cache_provider.ts'