Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

7.5 KB
Raw Blame
import { createHash } from 'node:crypto'
import { z } from 'zod'

import type { RedisLike } from './RedisCache'

const DEFAULT_CACHE_TTL_SECONDS = 7 * 24 * 60 * 60 // 7 days — hard expiry
const DEFAULT_FRESH_SECONDS = 60 * 10 // 10 minutes — after this, trigger a refresh
const DEFAULT_LOCK_TTL_SECONDS = 60 // writer lock auto-expires
const DEFAULT_WAIT_INTERVAL_MS = 200
const DEFAULT_WAIT_TIMEOUT_MS = 10_000

const pointerSchema = z.object({
    sha: z.string().regex(/^[a-f0-9]{64}$/),
    etag: z.string().optional(),
    validatedAt: z.number().finite(),
})

// A delayed 304 must not replace a newer pointer or refresh metadata for an evicted blob.
const TOUCH_CACHE = `
if redis.call('GET', KEYS[1]) ~= ARGV[1] then return 0 end
if redis.call('EXPIRE', KEYS[2], ARGV[3]) == 0 then return 0 end
redis.call('SET', KEYS[1], ARGV[2], 'EX', ARGV[3])
return 1
`

const RELEASE_LOCK = `
if redis.call('GET', KEYS[1]) == ARGV[1] then
    return redis.call('DEL', KEYS[1])
end
return 0
`

export interface SharedBlobCacheOptions {
    cacheTtlSeconds?: number
    freshSeconds?: number
    lockTtlSeconds?: number
    waitIntervalMs?: number
    waitTimeoutMs?: number
}

/**
 * Redis-backed helpers for an arbitrary binary blob, shared across instances.
 *
 * - Callers can coordinate single-writer refreshes with the `SET NX EX` lock,
 *   wait for another writer to publish on cold cache misses, and read/write
 *   immutable bytes through a single current-version pointer.
 * - Hard TTL keeps the cache available across long writer outages; a separate
 *   freshness timestamp lets callers decide when to refresh after the soft
 *   window.
 *
 * Each blob lives under a caller-supplied namespace, so one Redis can host
 * many independent shared blobs (e.g. context-mill archive, future bundles)
 * without colliding.
 */
export interface SharedBlobRecord extends SharedBlobVersion {
    bytes: Uint8Array
}

export interface SharedBlobVersion extends z.infer<typeof pointerSchema> {
    fresh: boolean
    serialized: string
}

export class SharedBlobCache {
    public readonly currentKey: string
    public readonly lockKey: string
    private readonly blobKeyPrefix: string
    private validatedAt: number | undefined

    private cacheTtlSeconds: number
    private freshSeconds: number
    private lockTtlSeconds: number
    private waitIntervalMs: number
    private waitTimeoutMs: number

    constructor(
        protected readonly redis: RedisLike,
        namespace: string,
        opts: SharedBlobCacheOptions = {}
    ) {
        // Separate layouts let old and new processes coexist during a rolling deploy.
        // The hash tag keeps the pointer, blob, and lock in one Redis Cluster slot, so
        // a script over two of them is accepted.
        const prefix = `mcp:shared-blob:{${namespace}}:v3`
        this.currentKey = `${prefix}:current`
        this.blobKeyPrefix = `${prefix}:blob`
        this.lockKey = `${prefix}:lock`

        this.cacheTtlSeconds = opts.cacheTtlSeconds ?? DEFAULT_CACHE_TTL_SECONDS
        this.freshSeconds = opts.freshSeconds ?? DEFAULT_FRESH_SECONDS
        this.lockTtlSeconds = opts.lockTtlSeconds ?? DEFAULT_LOCK_TTL_SECONDS
        this.waitIntervalMs = opts.waitIntervalMs ?? DEFAULT_WAIT_INTERVAL_MS
        this.waitTimeoutMs = opts.waitTimeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS
    }

    getLastValidatedAt(): number | undefined {
        return this.validatedAt
    }

    protected blobKey(sha: string): string {
        return `${this.blobKeyPrefix}:${sha}`
    }

    protected async readCache(version?: SharedBlobVersion): Promise<SharedBlobRecord | null> {
        const pointer = version ?? (await this.readVersion())
        if (!pointer) {
            return null
        }
        const key = this.blobKey(pointer.sha)
        const raw = await this.redis.get(key)
        if (raw === null) {
            return null
        }
        const buf = Buffer.from(raw, 'base64')
        const bytes = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength)
        if (hashBytes(bytes) !== pointer.sha) {
            // Remove only the corrupt content-addressed blob so a subsequent miss can repair it.
            await this.redis.del(key)
            throw new Error('Shared archive bytes do not match their content hash')
        }
        return { ...pointer, bytes }
    }

    /**
     * The small pointer is enough to check for updates without transferring archive bytes.
     */
    protected async readVersion(): Promise<SharedBlobVersion | null> {
        const serialized = await this.redis.get(this.currentKey)
        if (serialized === null) {
            return null
        }
        const pointer = pointerSchema.parse(JSON.parse(serialized))
        this.validatedAt = pointer.validatedAt
        return { ...pointer, fresh: Date.now() < pointer.validatedAt + this.freshSeconds * 1000, serialized }
    }

    protected async writeCache(bytes: Uint8Array, etag?: string): Promise<SharedBlobVersion> {
        const b64 = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString('base64')
        const pointer = { sha: hashBytes(bytes), etag, validatedAt: Date.now() }
        const serialized = JSON.stringify(pointer)
        // Publish immutable content first. A failed pointer write leaves the previous generation intact.
        await this.redis.set(this.blobKey(pointer.sha), b64, 'EX', this.cacheTtlSeconds)
        await this.redis.set(this.currentKey, serialized, 'EX', this.cacheTtlSeconds)
        this.validatedAt = pointer.validatedAt
        return { ...pointer, fresh: this.freshSeconds > 0, serialized }
    }

    /**
     * Refresh the validation timestamp and re-extend the hard TTLs without rewriting
     * the payload. Used when a conditional refresh confirms the cached bytes are
     * still current (HTTP 304), so the re-download and re-parse are skipped.
     */
    protected async touchCache(version: SharedBlobVersion): Promise<boolean> {
        const pointer = { sha: version.sha, etag: version.etag, validatedAt: Date.now() }
        const result = await this.redis.eval(
            TOUCH_CACHE,
            2,
            this.currentKey,
            this.blobKey(version.sha),
            version.serialized,
            JSON.stringify(pointer),
            this.cacheTtlSeconds
        )
        if (result === 1) {
            this.validatedAt = pointer.validatedAt
        }
        return result === 1
    }

    protected async acquireLock(token: string): Promise<boolean> {
        const result = await this.redis.set(this.lockKey, token, 'NX', 'EX', this.lockTtlSeconds)
        return result === 'OK'
    }

    protected async releaseLock(token: string): Promise<void> {
        try {
            await this.redis.eval(RELEASE_LOCK, 1, this.lockKey, token)
        } catch (err) {
            console.error(`[SharedBlobCache:${this.lockKey}] failed to release lock:`, err)
        }
    }

    protected async waitForCache(): Promise<Uint8Array | null> {
        const record = await this.waitForRecord()
        return record?.bytes ?? null
    }

    protected async waitForRecord(): Promise<SharedBlobRecord | null> {
        const start = Date.now()
        while (Date.now() - start < this.waitTimeoutMs) {
            await sleep(this.waitIntervalMs)
            const cached = await this.readCache()
            if (cached) {
                return cached
            }
        }
        return null
    }
}

export function hashBytes(bytes: Uint8Array): string {
    return createHash('sha256').update(bytes).digest('hex')
}

function sleep(ms: number): Promise<void> {
    return new Promise((resolve) => setTimeout(resolve, ms))
}