@avelonjs/conformance 0.1.0

package/src/fakes/payments.ts

@@ -0,0 +1,188 @@
+import {
+  Invalid,
+  NotFound,
+  Unauthenticated,
+  type CheckoutPaymentSurface,
+  type CheckoutSession,
+  type PaymentCustomer,
+  type PaymentDriver,
+  type PaymentSubscription,
+  type PaymentWebhook,
+  type SubscriptionPaymentSurface,
+  type WebhookPaymentSurface,
+} from '@avelonjs/core'
+
+const capabilities = {
+  subscriptions: true,
+  checkout: true,
+  webhooks: true,
+} as const
+
+interface FakePaymentsRaw {
+  readonly customers: number
+  readonly subscriptions: number
+  readonly checkouts: number
+}
+
+interface EncodedWebhook {
+  id: string
+  type: string
+  data: unknown
+  occurredAt: string
+}
+
+function isEncodedWebhook(value: unknown): value is EncodedWebhook {
+  if (typeof value !== 'object' || value === null) return false
+  return (
+    typeof Reflect.get(value, 'id') === 'string' &&
+    typeof Reflect.get(value, 'type') === 'string' &&
+    typeof Reflect.get(value, 'occurredAt') === 'string' &&
+    'data' in value
+  )
+}
+
+/** In-memory payments reference implementation used by conformance and application tests. */
+export class FakePayments
+  implements
+    PaymentDriver<typeof capabilities, FakePaymentsRaw>,
+    SubscriptionPaymentSurface,
+    CheckoutPaymentSurface,
+    WebhookPaymentSurface
+{
+  /** Driver implementation name. */
+  readonly name = 'fake'
+
+  /** Configured payments connection name. */
+  readonly instance: string
+
+  /** Exact optional-feature declaration. */
+  readonly capabilities = capabilities
+
+  readonly #customers = new Map<string, PaymentCustomer>()
+  readonly #subscriptions = new Map<string, PaymentSubscription>()
+  readonly #checkouts = new Map<string, CheckoutSession>()
+  #nextCustomer = 1
+  #nextSubscription = 1
+  #nextCheckout = 1
+
+  /** Creates an isolated payments connection. */
+  constructor(instance = 'default') {
+    this.instance = instance
+  }
+
+  /** Returns observable resource counts. */
+  raw(): FakePaymentsRaw {
+    return {
+      customers: this.#customers.size,
+      subscriptions: this.#subscriptions.size,
+      checkouts: this.#checkouts.size,
+    }
+  }
+
+  /** Creates a customer while retaining application metadata. */
+  async createCustomer(input: {
+    readonly email?: string
+    readonly metadata?: Readonly<Record<string, string>>
+  }): Promise<PaymentCustomer> {
+    const customer: PaymentCustomer = {
+      id: `customer-${this.#nextCustomer++}`,
+      ...(input.email === undefined ? {} : { email: input.email }),
+      metadata: { ...input.metadata },
+    }
+    this.#customers.set(customer.id, customer)
+    return customer
+  }
+
+  /** Retrieves a customer or raises the normalized missing-resource error. */
+  async customer(id: string): Promise<PaymentCustomer> {
+    const customer = this.#customers.get(id)
+    if (!customer) {
+      throw new NotFound(`Payment customer ${id} was not found.`, {
+        metadata: { resource: 'payment-customer', identifier: id },
+      })
+    }
+    return customer
+  }
+
+  /** Creates an active recurring subscription. */
+  async subscribe(customerId: string, priceId: string): Promise<PaymentSubscription> {
+    await this.customer(customerId)
+    const subscription: PaymentSubscription = {
+      id: `subscription-${this.#nextSubscription++}`,
+      customerId,
+      priceId,
+      status: 'active',
+      currentPeriodEndsAt: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000),
+    }
+    this.#subscriptions.set(subscription.id, subscription)
+    return subscription
+  }
+
+  /** Retrieves a recurring subscription. */
+  async subscription(id: string): Promise<PaymentSubscription> {
+    const subscription = this.#subscriptions.get(id)
+    if (!subscription) {
+      throw new NotFound(`Payment subscription ${id} was not found.`, {
+        metadata: { resource: 'payment-subscription', identifier: id },
+      })
+    }
+    return subscription
+  }
+
+  /** Cancels and returns a recurring subscription. */
+  async cancelSubscription(id: string): Promise<PaymentSubscription> {
+    const subscription = await this.subscription(id)
+    const canceled = { ...subscription, status: 'canceled' as const }
+    this.#subscriptions.set(id, canceled)
+    return canceled
+  }
+
+  /** Creates a hosted checkout session for a known or anonymous customer. */
+  async checkout(input: {
+    readonly customerId?: string
+    readonly priceId: string
+    readonly successUrl: string
+    readonly cancelUrl: string
+  }): Promise<CheckoutSession> {
+    if (input.customerId) await this.customer(input.customerId)
+    const id = `checkout-${this.#nextCheckout++}`
+    const session: CheckoutSession = {
+      id,
+      url: `https://checkout.example.test/${id}?price=${encodeURIComponent(input.priceId)}`,
+      expiresAt: new Date(Date.now() + 30 * 60 * 1000),
+    }
+    this.#checkouts.set(id, session)
+    return session
+  }
+
+  /** Verifies the assay signature and normalizes an encoded webhook event. */
+  async webhook(payload: Uint8Array, signature: string): Promise<PaymentWebhook> {
+    if (signature !== 'assay-signature') {
+      throw new Unauthenticated('The payment webhook signature is invalid.', {
+        metadata: { guard: 'payment-webhook' },
+      })
+    }
+
+    let decoded: unknown
+    try {
+      decoded = JSON.parse(new TextDecoder().decode(payload))
+    } catch (cause: unknown) {
+      throw new Invalid('The payment webhook payload is malformed.', {
+        metadata: { fields: { payload: ['Payload must be valid JSON.'] } },
+        cause,
+      })
+    }
+    if (!isEncodedWebhook(decoded) || Number.isNaN(Date.parse(decoded.occurredAt))) {
+      throw new Invalid('The payment webhook payload is malformed.', {
+        metadata: { fields: { payload: ['Payload does not contain a normalized event.'] } },
+      })
+    }
+
+    return {
+      id: decoded.id,
+      type: decoded.type,
+      data: decoded.data,
+      occurredAt: new Date(decoded.occurredAt),
+    }
+  }
+}

package/src/fakes/queue.ts

@@ -0,0 +1,205 @@
+import type {
+  DeadLetterQueueSurface,
+  DelayedQueueSurface,
+  FailedQueueJob,
+  QueueCapabilities,
+  QueueDriver,
+  QueueJob,
+  QueueReceipt,
+  RetryQueueSurface,
+} from '@avelonjs/core'
+
+const capabilities = {
+  delayed: true,
+  retries: true,
+  deadLetter: true,
+} as const
+
+const noRetryCapabilities = {
+  delayed: false,
+  retries: false,
+  deadLetter: false,
+} as const
+
+interface StoredQueueJob {
+  id: string
+  job: QueueJob
+  attempt: number
+  availableAt: number
+}
+
+interface FakeQueueRaw {
+  pending: number
+  failed: number
+}
+
+function failureMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+abstract class FakeQueueState<TCapabilities extends QueueCapabilities> implements QueueDriver<
+  TCapabilities,
+  FakeQueueRaw
+> {
+  /** Driver implementation name. */
+  readonly name = 'fake'
+
+  /** Configured queue connection name. */
+  readonly instance: string
+
+  /** Exact optional-feature declaration. */
+  readonly capabilities: TCapabilities
+
+  readonly #jobs = new Map<string, StoredQueueJob>()
+  readonly #failures = new Map<string, FailedQueueJob>()
+  readonly #maxTries: number
+  #nextId = 1
+
+  protected constructor(instance: string, declared: TCapabilities, maxTries: number) {
+    this.instance = instance
+    this.capabilities = declared
+    this.#maxTries = maxTries
+  }
+
+  /** Returns observable pending and failed job counts. */
+  raw(): FakeQueueRaw {
+    return { pending: this.#jobs.size, failed: this.#failures.size }
+  }
+
+  /** Enqueues a job for immediate delivery. */
+  async enqueue<TPayload>(job: QueueJob<TPayload>): Promise<string> {
+    return this.enqueueFor(job, Date.now())
+  }
+
+  /** Delivers each currently available job at most once during this drain call. */
+  async drain(
+    handler: (receipt: QueueReceipt) => Promise<void>,
+    options?: { readonly queue?: string; readonly limit?: number },
+  ): Promise<number> {
+    const available = [...this.#jobs.values()]
+      .filter(
+        (entry) =>
+          entry.availableAt <= Date.now() &&
+          (options?.queue === undefined || entry.job.queue === options.queue),
+      )
+      .slice(0, options?.limit)
+
+    for (const entry of available) {
+      entry.attempt += 1
+      const receipt = this.receipt(entry)
+      try {
+        await handler(receipt)
+        this.#jobs.delete(entry.id)
+      } catch (error: unknown) {
+        if (this.capabilities.retries && entry.attempt < this.#maxTries) continue
+        if (!this.capabilities.retries && this.redeliverFailuresWithoutRetries()) continue
+
+        if (this.capabilities.deadLetter) {
+          this.#failures.set(entry.id, {
+            ...receipt,
+            error: failureMessage(error),
+            failedAt: new Date(),
+          })
+        }
+        this.#jobs.delete(entry.id)
+      }
+    }
+
+    // A failed delivery still consumed worker capacity, so drain counts attempts rather than acks.
+    return available.length
+  }
+
+  protected enqueueFor<TPayload>(job: QueueJob<TPayload>, availableAt: number): string {
+    const id = `job-${this.#nextId++}`
+    this.#jobs.set(id, {
+      id,
+      job: { name: job.name, payload: job.payload, ...(job.queue ? { queue: job.queue } : {}) },
+      attempt: 0,
+      availableAt,
+    })
+    return id
+  }
+
+  protected release(id: string, delaySeconds = 0): void {
+    const job = this.#jobs.get(id)
+    if (job) job.availableAt = Date.now() + delaySeconds * 1000
+  }
+
+  protected failures(queue?: string): readonly FailedQueueJob[] {
+    return [...this.#failures.values()]
+      .filter((entry) => queue === undefined || entry.job.queue === queue)
+      .map((entry) => ({
+        ...entry,
+        job: { ...entry.job },
+        failedAt: new Date(entry.failedAt),
+      }))
+  }
+
+  protected replayFailure(id: string): void {
+    const failure = this.#failures.get(id)
+    if (!failure) return
+    this.#failures.delete(id)
+    this.#jobs.set(id, {
+      id,
+      job: { ...failure.job },
+      attempt: 0,
+      availableAt: Date.now(),
+    })
+  }
+
+  protected forgetFailure(id: string): void {
+    this.#failures.delete(id)
+  }
+
+  protected redeliverFailuresWithoutRetries(): boolean {
+    return false
+  }
+
+  private receipt(entry: StoredQueueJob): QueueReceipt {
+    return { id: entry.id, job: { ...entry.job }, attempt: entry.attempt }
+  }
+}
+
+/** In-memory retry-capable queue reference implementation. */
+export class FakeQueue
+  extends FakeQueueState<typeof capabilities>
+  implements DelayedQueueSurface, RetryQueueSurface, DeadLetterQueueSurface
+{
+  /** Creates an isolated queue with a deterministic terminal-attempt limit. */
+  constructor(instance = 'default', maxTries = 3) {
+    super(instance, capabilities, maxTries)
+  }
+
+  /** Enqueues a job no earlier than the supplied time. */
+  async enqueueAt<TPayload>(job: QueueJob<TPayload>, availableAt: Date): Promise<string> {
+    return this.enqueueFor(job, availableAt.getTime())
+  }
+
+  /** Releases a failed active job, optionally after a delay. */
+  async retry(id: string, delaySeconds?: number): Promise<void> {
+    this.release(id, delaySeconds)
+  }
+
+  /** Lists retained terminal failures. */
+  async failed(queue?: string): Promise<readonly FailedQueueJob[]> {
+    return this.failures(queue)
+  }
+
+  /** Replays a terminal failure with a fresh attempt budget. */
+  async replay(id: string): Promise<void> {
+    this.replayFailure(id)
+  }
+
+  /** Permanently removes a terminal failure. */
+  async forget(id: string): Promise<void> {
+    this.forgetFailure(id)
+  }
+}
+
+/** Retry-disabled queue fixture used to prove the contract's pinned throw behavior. */
+export class FakeQueueWithoutRetries extends FakeQueueState<typeof noRetryCapabilities> {
+  /** Creates an isolated at-most-once queue. */
+  constructor(instance = 'default') {
+    super(instance, noRetryCapabilities, 1)
+  }
+}

package/src/fakes/ratelimit.ts

@@ -0,0 +1,143 @@
+import {
+  Invalid,
+  type RateLimitAlgorithm,
+  type RateLimitCapabilities,
+  type RateLimitDecision,
+  type RateLimitDriver,
+  type RateLimitPolicy,
+} from '@avelonjs/core'
+
+interface TokenBucketState {
+  tokens: number
+  updatedAt: number
+}
+
+interface SlidingWindowEntry {
+  readonly at: number
+  readonly cost: number
+}
+
+interface FakeRateLimitRaw {
+  readonly keys: number
+}
+
+class FakeRateLimitBase<TAlgorithm extends RateLimitAlgorithm> implements RateLimitDriver<
+  RateLimitCapabilities<TAlgorithm>,
+  FakeRateLimitRaw
+> {
+  readonly name = 'fake'
+  readonly instance: string
+  readonly capabilities: RateLimitCapabilities<TAlgorithm>
+  readonly #tokenBuckets = new Map<string, TokenBucketState>()
+  readonly #slidingWindows = new Map<string, SlidingWindowEntry[]>()
+
+  constructor(algorithms: readonly TAlgorithm[], instance = 'default') {
+    this.capabilities = { algorithms }
+    this.instance = instance
+  }
+
+  raw(): FakeRateLimitRaw {
+    return { keys: this.#tokenBuckets.size + this.#slidingWindows.size }
+  }
+
+  async consume(key: string, policy: RateLimitPolicy, cost = 1): Promise<RateLimitDecision> {
+    this.validate(policy, cost)
+    return policy.algorithm === 'tokenBucket'
+      ? this.consumeTokenBucket(key, policy, cost)
+      : this.consumeSlidingWindow(key, policy, cost)
+  }
+
+  async reset(key: string): Promise<void> {
+    this.#tokenBuckets.delete(key)
+    this.#slidingWindows.delete(key)
+  }
+
+  private validate(policy: RateLimitPolicy, cost: number): void {
+    const fields: Record<string, readonly string[]> = {}
+    if (!this.capabilities.algorithms.some((algorithm) => algorithm === policy.algorithm)) {
+      fields.algorithm = [`${policy.algorithm} is not declared by this driver.`]
+    }
+    if (!Number.isInteger(policy.limit) || policy.limit <= 0) {
+      fields.limit = ['Limit must be a positive integer.']
+    }
+    if (!Number.isFinite(policy.intervalSeconds) || policy.intervalSeconds <= 0) {
+      fields.intervalSeconds = ['Interval must be greater than zero.']
+    }
+    if (!Number.isFinite(cost) || cost <= 0) fields.cost = ['Cost must be greater than zero.']
+    if (Object.keys(fields).length > 0) {
+      throw new Invalid('Invalid rate-limit policy.', { metadata: { fields } })
+    }
+  }
+
+  private consumeTokenBucket(
+    key: string,
+    policy: RateLimitPolicy,
+    cost: number,
+  ): RateLimitDecision {
+    const now = Date.now()
+    const intervalMs = policy.intervalSeconds * 1000
+    const refillPerMs = policy.limit / intervalMs
+    const state = this.#tokenBuckets.get(key) ?? { tokens: policy.limit, updatedAt: now }
+    state.tokens = Math.min(policy.limit, state.tokens + (now - state.updatedAt) * refillPerMs)
+    state.updatedAt = now
+    const allowed = state.tokens >= cost
+    if (allowed) state.tokens -= cost
+    this.#tokenBuckets.set(key, state)
+    const resetsAt = now + Math.ceil((policy.limit - state.tokens) / refillPerMs)
+    const retryAfterMs = allowed ? undefined : Math.ceil((cost - state.tokens) / refillPerMs)
+    return {
+      allowed,
+      remaining: Math.max(0, Math.floor(state.tokens)),
+      resetsAt,
+      ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
+    }
+  }
+
+  private consumeSlidingWindow(
+    key: string,
+    policy: RateLimitPolicy,
+    cost: number,
+  ): RateLimitDecision {
+    const now = Date.now()
+    const intervalMs = policy.intervalSeconds * 1000
+    const entries = (this.#slidingWindows.get(key) ?? []).filter(
+      (entry) => entry.at + intervalMs > now,
+    )
+    const used = entries.reduce((total, entry) => total + entry.cost, 0)
+    const allowed = used + cost <= policy.limit
+    if (allowed) entries.push({ at: now, cost })
+    this.#slidingWindows.set(key, entries)
+    const consumed = allowed ? used + cost : used
+    const resetsAt =
+      entries.length === 0 ? now : Math.max(...entries.map((entry) => entry.at)) + intervalMs
+    const retryAfterMs = allowed
+      ? undefined
+      : Math.max(0, (entries[0]?.at ?? now) + intervalMs - now)
+    return {
+      allowed,
+      remaining: Math.max(0, Math.floor(policy.limit - consumed)),
+      resetsAt,
+      ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
+    }
+  }
+}
+
+const allAlgorithms = ['tokenBucket', 'slidingWindow'] as const
+
+/** In-memory rate-limit reference implementation supporting both portable algorithms. */
+export class FakeRateLimit extends FakeRateLimitBase<(typeof allAlgorithms)[number]> {
+  /** Creates an isolated rate limiter with both algorithms enabled. */
+  constructor(instance = 'default') {
+    super(allAlgorithms, instance)
+  }
+}
+
+const noAlgorithms = [] as const
+
+/** In-memory rate-limit reference implementation with every algorithm disabled. */
+export class FakeRateLimitWithoutAlgorithms extends FakeRateLimitBase<never> {
+  /** Creates an isolated rate limiter with no configured algorithms. */
+  constructor(instance = 'default') {
+    super(noAlgorithms, instance)
+  }
+}

package/src/fakes/realtime.ts

@@ -0,0 +1,96 @@
+import {
+  type BroadcastRealtimeSurface,
+  type PresenceRealtimeSurface,
+  type RealtimeDriver,
+  type RealtimeMessage,
+  type RealtimeSubscription,
+} from '@avelonjs/core'
+
+const capabilities = {
+  presence: true,
+  broadcast: true,
+} as const
+
+type StoredHandler = (message: RealtimeMessage) => void | Promise<void>
+
+interface FakeRealtimeRaw {
+  readonly channels: number
+  readonly subscriptions: number
+}
+
+/** In-memory realtime reference implementation used by conformance and application tests. */
+export class FakeRealtime
+  implements
+    RealtimeDriver<typeof capabilities, FakeRealtimeRaw>,
+    PresenceRealtimeSurface,
+    BroadcastRealtimeSurface
+{
+  /** Driver implementation name. */
+  readonly name = 'fake'
+
+  /** Configured realtime connection name. */
+  readonly instance: string
+
+  /** Exact optional-feature declaration. */
+  readonly capabilities = capabilities
+
+  readonly #subscriptions = new Map<string, Set<StoredHandler>>()
+  readonly #presence = new Map<string, Readonly<Record<string, unknown>>>()
+
+  /** Creates an isolated realtime connection. */
+  constructor(instance = 'default') {
+    this.instance = instance
+  }
+
+  /** Returns observable channel and subscription counts. */
+  raw(): FakeRealtimeRaw {
+    let subscriptions = 0
+    for (const handlers of this.#subscriptions.values()) subscriptions += handlers.size
+    return { channels: this.#subscriptions.size, subscriptions }
+  }
+
+  /** Subscribes a handler to one named channel. */
+  async subscribe<TPayload = unknown>(
+    channel: string,
+    handler: (message: RealtimeMessage<TPayload>) => void | Promise<void>,
+  ): Promise<RealtimeSubscription> {
+    const stored: StoredHandler = (message) =>
+      handler({ ...message, payload: message.payload as TPayload })
+    const handlers = this.#subscriptions.get(channel) ?? new Set<StoredHandler>()
+    handlers.add(stored)
+    this.#subscriptions.set(channel, handlers)
+    let active = true
+
+    return {
+      channel,
+      unsubscribe: async () => {
+        if (!active) return
+        active = false
+        handlers.delete(stored)
+        if (handlers.size === 0) this.#subscriptions.delete(channel)
+      },
+    }
+  }
+
+  /** Broadcasts an event only to subscribers of the named channel. */
+  async broadcast<TPayload>(channel: string, event: string, payload: TPayload): Promise<void> {
+    const handlers = [...(this.#subscriptions.get(channel) ?? [])]
+    for (const handler of handlers) await handler({ channel, event, payload })
+  }
+
+  /** Joins presence for this driver instance on one channel. */
+  async joinPresence(channel: string, member: Readonly<Record<string, unknown>>): Promise<void> {
+    this.#presence.set(channel, member)
+  }
+
+  /** Leaves presence for this driver instance on one channel. */
+  async leavePresence(channel: string): Promise<void> {
+    this.#presence.delete(channel)
+  }
+
+  /** Lists the current member for this isolated driver instance. */
+  async presence(channel: string): Promise<readonly Readonly<Record<string, unknown>>[]> {
+    const member = this.#presence.get(channel)
+    return member ? [member] : []
+  }
+}