@defrex/autobuild-postgres-store 0.8.0

package/src/config.ts

@@ -0,0 +1,152 @@
+import { S3Client } from '@aws-sdk/client-s3'
+import type { Clock } from '@defrex/autobuild/plugin-sdk'
+import { resolvePostgresUrl } from './env'
+import { S3BlobStore } from './s3'
+import { openPostgresBuildStore, type PostgresBuildStore } from './store'
+import { VercelBlobStore } from './vercel'
+
+type Env = Record<string, string | undefined>
+const required = (env: Env, name: string): string => {
+  const value = env[name]?.trim()
+  if (!value) throw new Error(`${name} is required and must be nonblank`)
+  return value
+}
+const optional = (env: Env, name: string): string | undefined => env[name]?.trim() || undefined
+const bool = (env: Env, name: string): boolean | undefined => {
+  const value = optional(env, name)
+  if (value === undefined) return undefined
+  if (value === 'true') return true
+  if (value === 'false') return false
+  throw new Error(`${name} must be "true" or "false"`)
+}
+/** Optional positive integer. Absent ⇒ undefined (the caller's default applies). */
+const positiveInt = (env: Env, name: string): number | undefined => {
+  const value = optional(env, name)
+  if (value === undefined) return undefined
+  const parsed = Number(value)
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    throw new Error(`${name} must be a positive integer, got ${value}`)
+  }
+  return parsed
+}
+
+export type PostgresStoreConfig =
+  | {
+      url: string
+      backend: 's3'
+      bucket: string
+      region: string
+      accessKeyId: string
+      secretAccessKey: string
+      endpoint?: string
+      sessionToken?: string
+      forcePathStyle?: boolean
+      prefix?: string
+      /** Artifact retention bound (store/retention.ts); present only when
+       * AB_ARTIFACT_RETENTION_MAX_REVISIONS is set — absent means the store's
+       * documented default (200) applies. */
+      retention?: { maxRevisions: number }
+    }
+  | {
+      url: string
+      backend: 'vercel'
+      access: 'public' | 'private'
+      prefix?: string
+      token?: string
+      oidcToken?: string
+      storeId?: string
+      /** See the s3 branch. */
+      retention?: { maxRevisions: number }
+    }
+
+export function parsePostgresStoreEnv(env: Env): PostgresStoreConfig {
+  const url = resolvePostgresUrl(env)
+  const backend = required(env, 'AB_BLOB_BACKEND')
+  const prefix = optional(env, 'AB_BLOB_PREFIX')
+  const maxRevisions = positiveInt(env, 'AB_ARTIFACT_RETENTION_MAX_REVISIONS')
+  const retention = maxRevisions === undefined ? undefined : { maxRevisions }
+  if (backend === 's3') {
+    const endpoint = optional(env, 'AB_S3_ENDPOINT')
+    const sessionToken = optional(env, 'AB_S3_SESSION_TOKEN')
+    const forcePathStyle = bool(env, 'AB_S3_FORCE_PATH_STYLE')
+    return {
+      url,
+      backend,
+      bucket: required(env, 'AB_S3_BUCKET'),
+      region: required(env, 'AB_S3_REGION'),
+      accessKeyId: required(env, 'AB_S3_ACCESS_KEY_ID'),
+      secretAccessKey: required(env, 'AB_S3_SECRET_ACCESS_KEY'),
+      ...(endpoint ? { endpoint } : {}),
+      ...(sessionToken ? { sessionToken } : {}),
+      ...(forcePathStyle !== undefined ? { forcePathStyle } : {}),
+      ...(prefix ? { prefix } : {}),
+      ...(retention ? { retention } : {}),
+    }
+  }
+  if (backend === 'vercel') {
+    const access = required(env, 'AB_VERCEL_BLOB_ACCESS')
+    if (access !== 'public' && access !== 'private') {
+      throw new Error('AB_VERCEL_BLOB_ACCESS must be "public" or "private"')
+    }
+    const token = optional(env, 'BLOB_READ_WRITE_TOKEN')
+    const oidcToken = optional(env, 'VERCEL_OIDC_TOKEN')
+    const storeId = optional(env, 'BLOB_STORE_ID')
+    if (!token && !(oidcToken && storeId)) {
+      throw new Error(
+        'Vercel Blob requires BLOB_READ_WRITE_TOKEN or both VERCEL_OIDC_TOKEN and BLOB_STORE_ID',
+      )
+    }
+    return {
+      url,
+      backend,
+      access,
+      ...(prefix ? { prefix } : {}),
+      ...(token ? { token } : { oidcToken: oidcToken!, storeId: storeId! }),
+      ...(retention ? { retention } : {}),
+    }
+  }
+  throw new Error('AB_BLOB_BACKEND must be "s3" or "vercel"')
+}
+
+export async function openPostgresBuildStoreFromEnv(
+  env: Env,
+  options: { clock?: Clock } = {},
+): Promise<PostgresBuildStore> {
+  const config = parsePostgresStoreEnv(env)
+  const storeOptions = {
+    ...options,
+    ...(config.retention ? { retention: config.retention } : {}),
+  }
+  if (config.backend === 's3') {
+    const client = new S3Client({
+      region: config.region,
+      ...(config.endpoint ? { endpoint: config.endpoint } : {}),
+      ...(config.forcePathStyle !== undefined ? { forcePathStyle: config.forcePathStyle } : {}),
+      credentials: {
+        accessKeyId: config.accessKeyId,
+        secretAccessKey: config.secretAccessKey,
+        ...(config.sessionToken ? { sessionToken: config.sessionToken } : {}),
+      },
+    })
+    return openPostgresBuildStore(
+      config.url,
+      new S3BlobStore({
+        client,
+        bucket: config.bucket,
+        ...(config.prefix ? { prefix: config.prefix } : {}),
+      }),
+      storeOptions,
+    )
+  }
+  return openPostgresBuildStore(
+    config.url,
+    new VercelBlobStore({
+      access: config.access,
+      ...(config.prefix ? { prefix: config.prefix } : {}),
+      ...(config.token
+        ? { token: config.token }
+        : { oidcToken: config.oidcToken!, storeId: config.storeId! }),
+    }),
+    storeOptions,
+  )
+}

package/src/env.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, test } from 'bun:test'
+import { describePostgresTarget, MISSING_POSTGRES_URL_MESSAGE, resolvePostgresUrl } from './env'
+
+describe('PostgreSQL URL resolution', () => {
+  test('prefers the explicit Autobuild variable', () => {
+    expect(
+      resolvePostgresUrl({
+        AB_POSTGRES_URL: ' postgres://explicit ',
+        DATABASE_URL: 'postgres://ambient',
+      }),
+    ).toBe('postgres://explicit')
+  })
+
+  test('falls back to the conventional DATABASE_URL', () => {
+    expect(resolvePostgresUrl({ DATABASE_URL: 'postgres://ambient' })).toBe('postgres://ambient')
+    expect(resolvePostgresUrl({ AB_POSTGRES_URL: '  ', DATABASE_URL: 'postgres://ambient' })).toBe(
+      'postgres://ambient',
+    )
+  })
+
+  test('names both variables when neither is set', () => {
+    expect(() => resolvePostgresUrl({})).toThrow(MISSING_POSTGRES_URL_MESSAGE)
+    expect(() =>
+      resolvePostgresUrl({
+        AB_POSTGRES_URL: '',
+        DATABASE_URL_UNPOOLED: 'postgres://direct',
+        POSTGRES_URL: 'postgres://legacy',
+      }),
+    ).toThrow(MISSING_POSTGRES_URL_MESSAGE)
+  })
+})
+
+describe('PostgreSQL target description', () => {
+  test('names the host and database without credentials', () => {
+    expect(
+      describePostgresTarget(
+        'postgresql://neondb_owner:hunter2@ep-example-pooler.neon.tech/neondb?sslmode=require',
+      ),
+    ).toBe('ep-example-pooler.neon.tech/neondb')
+    expect(describePostgresTarget('postgres://user:secret@db.internal:6432')).toBe(
+      'db.internal:6432',
+    )
+  })
+
+  test('never echoes an unparsable value', () => {
+    expect(describePostgresTarget('not a url with secret')).toBe('the configured database')
+  })
+})

package/src/env.ts

@@ -0,0 +1,31 @@
+/** PostgreSQL connection URL selection shared by the adapter, the migration
+ * CLI, and the hosted web session store. */
+export type PostgresEnv = Record<string, string | undefined>
+
+/** Variables consulted in precedence order: the explicit Autobuild name wins
+ * over the conventional `DATABASE_URL` that hosting integrations inject. */
+export const POSTGRES_URL_VARIABLES = ['AB_POSTGRES_URL', 'DATABASE_URL'] as const
+
+export const MISSING_POSTGRES_URL_MESSAGE =
+  'AB_POSTGRES_URL or DATABASE_URL is required and must be nonblank'
+
+/** Resolve the first nonblank connection URL. Blank values are skipped so an
+ * empty override cannot shadow the conventional variable. */
+export function resolvePostgresUrl(env: PostgresEnv): string {
+  for (const name of POSTGRES_URL_VARIABLES) {
+    const value = env[name]?.trim()
+    if (value) return value
+  }
+  throw new Error(MISSING_POSTGRES_URL_MESSAGE)
+}
+
+/** Credential-free description of a connection URL for logs: host and database. */
+export function describePostgresTarget(url: string): string {
+  try {
+    const parsed = new URL(url)
+    const database = parsed.pathname.replace(/^\/+/, '')
+    return database ? `${parsed.host}/${database}` : parsed.host
+  } catch {
+    return 'the configured database'
+  }
+}

package/src/event-wait-poll-ms.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, test } from 'bun:test'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { EVENT_WAIT_POLL_MS as fromAdapter } from '@defrex/autobuild/store-adapter'
+import { EVENT_WAIT_POLL_MS as fromStore } from './store'
+
+describe('EVENT_WAIT_POLL_MS unification (AUT-388)', () => {
+  const source = readFileSync(join(import.meta.dir, 'store.ts'), 'utf8')
+
+  test('store.ts does not redefine the constant (AUT-388)', () => {
+    expect(source).not.toMatch(/const\s+EVENT_WAIT_POLL_MS\s*=/)
+  })
+
+  test('store.ts imports the core constant via @defrex/autobuild/store-adapter', () => {
+    expect(source).toMatch(
+      /import\s*\{[^}]*\bEVENT_WAIT_POLL_MS\b[^}]*\}\s*from\s*'@defrex\/autobuild\/store-adapter'/s,
+    )
+  })
+
+  test('the postgres-store export is the core binding, not a copy', () => {
+    expect(fromStore).toBe(fromAdapter)
+  })
+})

package/src/index.ts

@@ -0,0 +1,41 @@
+export {
+  AUTH_SCHEMA_CHECKSUM,
+  AUTH_SCHEMA_DDL,
+  AUTH_SCHEMA_VERSION,
+  assertAuthSchema,
+} from './auth-schema'
+export { openPostgresBuildStoreFromEnv, parsePostgresStoreEnv } from './config'
+export type { PostgresStoreConfig } from './config'
+export {
+  describePostgresTarget,
+  MISSING_POSTGRES_URL_MESSAGE,
+  POSTGRES_URL_VARIABLES,
+  resolvePostgresUrl,
+} from './env'
+export type { PostgresEnv } from './env'
+export { S3BlobStore, blobPath } from './s3'
+export type { S3BlobStoreOptions } from './s3'
+export {
+  MIGRATE_COMMAND,
+  SCHEMA_CHECKSUM,
+  SCHEMA_VERSION,
+  TICKET_SCHEMA_CHECKSUM,
+  TICKET_SCHEMA_VERSION,
+  assertSchema,
+  assertTicketSchema,
+  migratePostgres,
+} from './schema'
+export {
+  EVENT_WAIT_POLL_MS,
+  openPostgresBuildStore,
+  PostgresBuildStore,
+} from './store'
+export type { PostgresBuildStoreOptions } from './store'
+export {
+  openPostgresTicketDatabase,
+  PostgresTicketDatabase,
+  PostgresTicketSource,
+} from './tickets'
+export type { PostgresTicketContext, PostgresTicketLifecycle } from './tickets'
+export { VercelBlobStore } from './vercel'
+export type { VercelBlobStoreOptions } from './vercel'