@avelonjs/conformance 0.1.0

package/src/fakes/search.ts

@@ -0,0 +1,127 @@
+import {
+  Invalid,
+  type SearchCapabilities,
+  type SearchDocument,
+  type SearchDriver,
+  type SearchOptions,
+  type SearchResult,
+} from '@avelonjs/core'
+
+interface FakeSearchRaw {
+  readonly indexes: number
+  readonly documents: number
+}
+
+class FakeSearchBase<TCapabilities extends SearchCapabilities> implements SearchDriver<
+  TCapabilities,
+  FakeSearchRaw
+> {
+  readonly name = 'fake'
+  readonly instance: string
+  readonly capabilities: TCapabilities
+  readonly #indexes = new Map<string, Map<string, SearchDocument>>()
+
+  constructor(capabilities: TCapabilities, instance = 'default') {
+    this.capabilities = capabilities
+    this.instance = instance
+  }
+
+  raw(): FakeSearchRaw {
+    let documents = 0
+    for (const index of this.#indexes.values()) documents += index.size
+    return { indexes: this.#indexes.size, documents }
+  }
+
+  async index(name: string, documents: readonly SearchDocument[]): Promise<void> {
+    const index = this.#indexes.get(name) ?? new Map<string, SearchDocument>()
+    for (const document of documents) {
+      index.set(document.id, { id: document.id, fields: { ...document.fields } })
+    }
+    this.#indexes.set(name, index)
+  }
+
+  async remove(name: string, ids: readonly string[]): Promise<void> {
+    const index = this.#indexes.get(name)
+    for (const id of ids) index?.delete(id)
+  }
+
+  async query<TDocument extends SearchDocument = SearchDocument>(
+    name: string,
+    query: string,
+    options: SearchOptions = {},
+  ): Promise<SearchResult<TDocument>> {
+    this.validateOptions(options)
+    const needle = query.toLocaleLowerCase()
+    const matches = [...(this.#indexes.get(name)?.values() ?? [])].filter((document) => {
+      const matchesQuery =
+        needle.length === 0 ||
+        Object.values(document.fields).some(
+          (value) => typeof value === 'string' && value.toLocaleLowerCase().includes(needle),
+        )
+      const matchesFilters = Object.entries(options.filters ?? {}).every(([field, value]) =>
+        Object.is(document.fields[field], value),
+      )
+      return matchesQuery && matchesFilters
+    })
+
+    const offset = options.offset ?? 0
+    const limit = options.limit ?? matches.length
+    const page = matches.slice(offset, offset + limit)
+    const facets = options.facets
+      ? Object.fromEntries(
+          options.facets.map((field) => {
+            const counts: Record<string, number> = {}
+            for (const document of matches) {
+              const value = document.fields[field]
+              if (value === undefined) continue
+              const key = String(value)
+              counts[key] = (counts[key] ?? 0) + 1
+            }
+            return [field, counts]
+          }),
+        )
+      : undefined
+
+    return {
+      hits: page.map((document) => ({ document: document as TDocument, score: 1 })),
+      total: matches.length,
+      ...(facets === undefined ? {} : { facets }),
+    }
+  }
+
+  private validateOptions(options: SearchOptions): void {
+    const fields: Record<string, readonly string[]> = {}
+    if (options.limit !== undefined && (!Number.isInteger(options.limit) || options.limit < 0)) {
+      fields.limit = ['Limit must be a non-negative integer.']
+    }
+    if (options.offset !== undefined && (!Number.isInteger(options.offset) || options.offset < 0)) {
+      fields.offset = ['Offset must be a non-negative integer.']
+    }
+    if (options.facets && !this.capabilities.facets) {
+      fields.facets = ['Facet queries are not declared by this driver.']
+    }
+    if (Object.keys(fields).length > 0) {
+      throw new Invalid('Invalid search options.', { metadata: { fields } })
+    }
+  }
+}
+
+const allCapabilities = { facets: true } as const
+
+/** In-memory search reference implementation with facet support. */
+export class FakeSearch extends FakeSearchBase<typeof allCapabilities> {
+  /** Creates an isolated search connection with facets enabled. */
+  constructor(instance = 'default') {
+    super(allCapabilities, instance)
+  }
+}
+
+const noFacetCapabilities = { facets: false } as const
+
+/** In-memory search reference implementation without facet support. */
+export class FakeSearchWithoutFacets extends FakeSearchBase<typeof noFacetCapabilities> {
+  /** Creates an isolated search connection with facets disabled. */
+  constructor(instance = 'default') {
+    super(noFacetCapabilities, instance)
+  }
+}

package/src/fakes/social.ts

@@ -0,0 +1,83 @@
+import { Invalid, Unauthenticated, type SocialDriver, type SocialIdentity } from '@avelonjs/core'
+
+const capabilities = {
+  providers: ['primary', 'secondary'] as const,
+} as const
+
+type Provider = (typeof capabilities.providers)[number]
+
+interface FakeSocialProfile {
+  displayName: string
+}
+
+interface FakeSocialRaw {
+  pendingStates: number
+}
+
+function invalid(field: string, message: string): Invalid {
+  return new Invalid(message, { metadata: { fields: { [field]: [message] } } })
+}
+
+function unauthenticated(message: string): Unauthenticated {
+  return new Unauthenticated(message, { metadata: { guard: 'social' } })
+}
+
+function isProvider(provider: string): provider is Provider {
+  return capabilities.providers.some((candidate) => candidate === provider)
+}
+
+/** In-memory social authorization reference implementation used by conformance tests. */
+export class FakeSocial implements SocialDriver<
+  typeof capabilities,
+  FakeSocialRaw,
+  FakeSocialProfile
+> {
+  /** Driver implementation name. */
+  readonly name = 'fake'
+
+  /** Configured social connection name. */
+  readonly instance = 'default'
+
+  /** Exact configured-provider declaration. */
+  readonly capabilities = capabilities
+
+  readonly #states = new Map<Provider, string>()
+  #nextState = 1
+
+  /** Returns the count of pending authorization states. */
+  raw(): FakeSocialRaw {
+    return { pendingStates: this.#states.size }
+  }
+
+  /** Builds an authorization URL for a configured provider and records its CSRF state. */
+  async redirect(provider: string, callbackUrl: string, state?: string): Promise<string> {
+    if (!isProvider(provider)) throw invalid('provider', 'Provider is not configured.')
+    const expectedState = state ?? `assay-state-${this.#nextState++}`
+    this.#states.set(provider, expectedState)
+    const url = new URL(`https://auth.example.test/${provider}/authorize`)
+    url.searchParams.set('redirect_uri', callbackUrl)
+    url.searchParams.set('state', expectedState)
+    return url.toString()
+  }
+
+  /** Verifies authorization state and returns normalized social identity data. */
+  async callback(
+    provider: string,
+    params: Readonly<Record<string, string>>,
+    _callbackUrl: string,
+  ): Promise<SocialIdentity<FakeSocialProfile>> {
+    if (!isProvider(provider)) throw invalid('provider', 'Provider is not configured.')
+    const expectedState = this.#states.get(provider)
+    if (!expectedState || !params.state || params.state !== expectedState) {
+      throw unauthenticated('Authorization state could not be verified.')
+    }
+    this.#states.delete(provider)
+    if (params.error) throw unauthenticated(`Authorization failed: ${params.error}.`)
+    if (!params.code) throw invalid('code', 'Authorization code is required.')
+    return {
+      provider,
+      subject: `subject-${params.code}`,
+      profile: { displayName: 'Assay Actor' },
+    }
+  }
+}

package/src/fakes/storage.ts

@@ -0,0 +1,125 @@
+import {
+  NotFound,
+  type SignedUrlStorageSurface,
+  type StorageDriver,
+  type StorageObject,
+} from '@avelonjs/core'
+
+const capabilities = {
+  signedUrls: true,
+  transforms: [] as const,
+} as const
+
+interface StoredObject {
+  contents: Uint8Array
+  contentType?: string
+}
+
+interface FakeStorageRaw {
+  objects: number
+}
+
+async function readContents(contents: Uint8Array | AsyncIterable<Uint8Array>): Promise<Uint8Array> {
+  if (contents instanceof Uint8Array) return contents.slice()
+
+  const chunks: Uint8Array[] = []
+  let size = 0
+  for await (const chunk of contents) {
+    const copy = chunk.slice()
+    chunks.push(copy)
+    size += copy.byteLength
+  }
+
+  const result = new Uint8Array(size)
+  let offset = 0
+  for (const chunk of chunks) {
+    result.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return result
+}
+
+function objectUrl(contents: Uint8Array, contentType?: string): string {
+  const buffer = new ArrayBuffer(contents.byteLength)
+  new Uint8Array(buffer).set(contents)
+  return URL.createObjectURL(new Blob([buffer], { type: contentType }))
+}
+
+/** In-memory storage reference implementation used by conformance and application tests. */
+export class FakeStorage
+  implements StorageDriver<typeof capabilities, FakeStorageRaw>, SignedUrlStorageSurface
+{
+  /** Driver implementation name. */
+  readonly name = 'fake'
+
+  /** Configured storage disk name. */
+  readonly instance: string
+
+  /** Exact optional-feature declaration. */
+  readonly capabilities = capabilities
+
+  readonly #objects = new Map<string, StoredObject>()
+
+  /** Creates an isolated storage disk with the supplied instance name. */
+  constructor(instance = 'default') {
+    this.instance = instance
+  }
+
+  /** Returns the number of objects held by this isolated fake disk. */
+  raw(): FakeStorageRaw {
+    return { objects: this.#objects.size }
+  }
+
+  /** Stores an exact byte copy and returns normalized object metadata. */
+  async put(
+    path: string,
+    contents: Uint8Array | AsyncIterable<Uint8Array>,
+    options?: { readonly contentType?: string },
+  ): Promise<StorageObject> {
+    const stored: StoredObject = {
+      contents: await readContents(contents),
+      ...(options?.contentType === undefined ? {} : { contentType: options.contentType }),
+    }
+    this.#objects.set(path, stored)
+    return {
+      path,
+      size: stored.contents.byteLength,
+      ...(stored.contentType === undefined ? {} : { contentType: stored.contentType }),
+    }
+  }
+
+  /** Reads an exact byte copy or raises `NotFound` when the path is absent. */
+  async get(path: string): Promise<Uint8Array> {
+    const stored = this.#objects.get(path)
+    if (!stored) {
+      throw new NotFound(`Storage object ${path} was not found.`, {
+        metadata: { resource: 'storage-object', identifier: path },
+      })
+    }
+    return stored.contents.slice()
+  }
+
+  /** Deletes an object when present. */
+  async delete(path: string): Promise<void> {
+    this.#objects.delete(path)
+  }
+
+  /** Reports whether an object exists. */
+  async exists(path: string): Promise<boolean> {
+    return this.#objects.has(path)
+  }
+
+  /** Creates a fetchable read URL and revokes it when its lifetime elapses. */
+  async signedUrl(path: string, expiresInSeconds: number): Promise<string> {
+    const stored = this.#objects.get(path)
+    if (!stored) {
+      throw new NotFound(`Storage object ${path} was not found.`, {
+        metadata: { resource: 'storage-object', identifier: path },
+      })
+    }
+
+    const url = objectUrl(stored.contents, stored.contentType)
+    setTimeout(() => URL.revokeObjectURL(url), expiresInSeconds * 1000)
+    return url
+  }
+}

package/src/fakes/tokens.ts

@@ -0,0 +1,106 @@
+import {
+  Unauthenticated,
+  type IssuedToken,
+  type TokenDriver,
+  type TokenIssueOptions,
+  type TokenRecord,
+} from '@avelonjs/core'
+
+const capabilities = {
+  abilities: true,
+  expiration: true,
+} as const
+
+interface StoredToken extends TokenRecord {
+  hash: string
+  revoked: boolean
+}
+
+interface FakeTokenRaw {
+  hashes: readonly string[]
+}
+
+function unauthenticated(): Unauthenticated {
+  return new Unauthenticated('The API token is invalid or expired.', {
+    metadata: { guard: 'tokens' },
+  })
+}
+
+async function hash(plainText: string): Promise<string> {
+  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(plainText))
+  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0')).join('')
+}
+
+function copyRecord(token: TokenRecord): TokenRecord {
+  return {
+    id: token.id,
+    subject: token.subject,
+    name: token.name,
+    abilities: [...token.abilities],
+    createdAt: new Date(token.createdAt),
+    expiresAt: token.expiresAt ? new Date(token.expiresAt) : null,
+  }
+}
+
+/** In-memory API-token reference implementation used by conformance and application tests. */
+export class FakeTokens implements TokenDriver<typeof capabilities, FakeTokenRaw> {
+  /** Driver implementation name. */
+  readonly name = 'fake'
+
+  /** Configured token issuer name. */
+  readonly instance = 'default'
+
+  /** Exact issuance-feature declaration. */
+  readonly capabilities = capabilities
+
+  readonly #tokens: StoredToken[] = []
+  #nextId = 1
+
+  /** Returns stored hashes without exposing plaintext token values. */
+  raw(): FakeTokenRaw {
+    return { hashes: this.#tokens.map((token) => token.hash) }
+  }
+
+  /** Authenticates an active plaintext token and returns its safe metadata. */
+  async verify(plainText: string): Promise<TokenRecord> {
+    const candidateHash = await hash(plainText)
+    const token = this.#tokens.find((candidate) => candidate.hash === candidateHash)
+    if (
+      !token ||
+      token.revoked ||
+      (token.expiresAt !== null && token.expiresAt.getTime() <= Date.now())
+    ) {
+      throw unauthenticated()
+    }
+    return copyRecord(token)
+  }
+
+  /** Issues a token and returns its plaintext exactly once. */
+  async issue(name: string, options: TokenIssueOptions = {}): Promise<IssuedToken> {
+    const id = `token-${this.#nextId++}`
+    const plainText = `avelon-assay-${id}-${crypto.randomUUID()}`
+    const record: StoredToken = {
+      id,
+      subject: 'assay-subject',
+      name,
+      abilities: [...(options.abilities ?? [])],
+      createdAt: new Date(),
+      expiresAt: options.expiresAt ? new Date(options.expiresAt) : null,
+      hash: await hash(plainText),
+      revoked: false,
+    }
+    this.#tokens.push(record)
+    return { ...copyRecord(record), plainText }
+  }
+
+  /** Lists safe token metadata for the current actor. */
+  async list(): Promise<readonly TokenRecord[]> {
+    return this.#tokens.map(copyRecord)
+  }
+
+  /** Revokes one token by stable identifier. */
+  async revoke(id: string): Promise<void> {
+    const token = this.#tokens.find((candidate) => candidate.id === id)
+    if (token) token.revoked = true
+  }
+}

package/src/harness.ts

@@ -0,0 +1,103 @@
+/**
+ * Shared harness for every contract conformance suite.
+ *
+ * A suite is written from the contract by an author who does not implement it, and is run by both
+ * the contract's reference fake and every real driver. That is what makes a passing driver mean
+ * something: the assertions were not written by the person trying to satisfy them.
+ */
+
+/**
+ * Supplies the subject under test to a suite.
+ *
+ * `create` must return a driver in a known-empty state, because suites assume they own the world
+ * they observe. A driver backed by a live service is responsible for namespacing and cleanup.
+ */
+export interface SuiteContext<TDriver> {
+  /** Human-readable name of the implementation, used in test titles. */
+  name: string
+  /** Returns a driver in a known-empty state. Called once per test. */
+  create(): Promise<TDriver> | TDriver
+  /** Releases anything `create` acquired. Called after every test, including failures. */
+  cleanup?(driver: TDriver): Promise<void> | void
+  /** Returns a vendor-issued password recovery token for the fixture identity. */
+  recoveryToken?(email: string): Promise<string>
+  /** Returns the response code for a pending MFA challenge. */
+  mfaCode?(challengeId: string): Promise<string>
+  /** Verified sender address used by live mail providers. */
+  mailSender?: string
+  /** Deliverable addresses used by the mail suite. */
+  mailRecipients?: {
+    readonly to: readonly [string, string]
+    readonly replyTo: readonly [string, string]
+    readonly cc: string
+    readonly bcc: string
+    readonly configured: string
+  }
+  /** Delay before a queued job becomes visible. */
+  queueDelayMs?: number
+  /** Time allowed for a delayed queued job to become visible. */
+  queueSettleMs?: number
+  /**
+   * Marks a suite as running against a live external service. Suites use this only to skip
+   * assertions that a fake cannot meaningfully make, never to weaken an assertion.
+   */
+  live?: boolean
+}
+
+/**
+ * Asserts a driver's declared capabilities match what it actually exposes, in both directions.
+ *
+ * Declaring a capability and omitting the method is a lie a caller discovers at runtime.
+ * Implementing a method while declaring the capability false is worse, because someone will call
+ * it and it will work until the driver is swapped. Both are failures here.
+ *
+ * This helper covers method-gated capabilities only. Capabilities that narrow accepted arguments,
+ * such as notification channels or rate-limit algorithms, are checked behaviorally by their suite:
+ * declared values must work and undeclared values must be rejected.
+ *
+ * @param driver The implementation under test.
+ * @param capability The capability key being checked.
+ * @param declared Whether the driver declares the capability as available.
+ * @param methods Method names that must exist when declared, and must be absent when not.
+ */
+export function assertCapabilitySurface(
+  driver: object,
+  capability: string,
+  declared: boolean,
+  methods: readonly string[],
+): void {
+  for (const method of methods) {
+    const candidate: unknown = Reflect.get(driver, method)
+    const present = typeof candidate === 'function'
+    if (declared && !present) {
+      throw new Error(
+        `${capability} is declared available but ${method}() is missing. ` +
+          `A declared capability must be callable.`,
+      )
+    }
+    if (!declared && present) {
+      throw new Error(
+        `${capability} is declared unavailable but ${method}() is implemented. ` +
+          `Someone will call it, and it will break when the driver is swapped.`,
+      )
+    }
+  }
+}
+
+/**
+ * Runs an operation expected to fail, and returns the thrown value for taxonomy assertions.
+ *
+ * Suites assert the framework error taxonomy rather than a vendor's code, because a vendor code
+ * reaching application code means the abstraction has already leaked through the error channel.
+ *
+ * @param operation The operation expected to throw.
+ * @returns The thrown value.
+ */
+export async function captureFailure(operation: () => Promise<unknown>): Promise<unknown> {
+  try {
+    await operation()
+  } catch (error: unknown) {
+    return error
+  }
+  throw new Error('Expected the operation to fail, but it resolved.')
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+/** Fakes and harness only. Suites import `bun:test` and live at `@avelonjs/conformance/suites`. */
+export { assertCapabilitySurface, captureFailure } from './harness'
+export type { SuiteContext } from './harness'
+export { FakeAI } from './fakes/ai'
+export { FakeCache } from './fakes/cache'
+export { FakeDatabase } from './fakes/database'
+export { FakeFlags, FakeFlagsWithoutTargeting } from './fakes/flags'
+export { FakeIdentity } from './fakes/identity'
+export { FakeLogs } from './fakes/logs'
+export type { FakeTraceRecord } from './fakes/logs'
+export { FakeMail } from './fakes/mail'
+export { FakeNotifications, FakeNotificationsWithoutChannels } from './fakes/notifications'
+export type { FakeSentNotification } from './fakes/notifications'
+export { FakePayments } from './fakes/payments'
+export { FakeQueue, FakeQueueWithoutRetries } from './fakes/queue'
+export { FakeRateLimit, FakeRateLimitWithoutAlgorithms } from './fakes/ratelimit'
+export { FakeRealtime } from './fakes/realtime'
+export { FakeSearch, FakeSearchWithoutFacets } from './fakes/search'
+export { FakeSocial } from './fakes/social'
+export { FakeStorage } from './fakes/storage'
+export { FakeTokens } from './fakes/tokens'