bunderstack 0.17.0-beta.2 → 0.17.0-beta.3

package/src/storage/buckets.ts

@@ -1,308 +0,0 @@
-// src/storage/buckets.ts
-import type { OperationRule, ScopeResolver } from '../access'
-
-// ---------------------------------------------------------------------------
-// Input types (developer-facing config)
-// ---------------------------------------------------------------------------
-
-export type BucketBackendInput =
-  | {
-      s3: {
-        bucket: string
-        region?: string
-        endpoint?: string
-        publicUrl?: string
-      }
-    }
-  | { local: string }
-
-export type BucketConfigInput = {
-  visibility?: 'public' | 'private'
-  access?: {
-    create?: OperationRule
-    get?: OperationRule
-    delete?: OperationRule
-  }
-  upload?: { maxSize?: string | number; accept?: string[] }
-  transforms?: boolean
-  scope?: {
-    read?: ScopeResolver
-    write?: ScopeResolver
-  }
-  quota?: { perUser?: string | number; perScope?: string | number }
-} & Partial<BucketBackendInput>
-
-export type StorageConfigInput = {
-  s3?: true | { endpoint?: string }
-  local?: true | string
-  defaultBucket?: string
-  buckets?: Record<string, BucketConfigInput>
-}
-
-// ---------------------------------------------------------------------------
-// Resolved types (internal)
-// ---------------------------------------------------------------------------
-
-export type ResolvedBackend =
-  | { type: 'local'; path: string }
-  | {
-      type: 's3'
-      bucket: string
-      region: string
-      endpoint?: string
-      accessKeyId: string
-      secretAccessKey: string
-      publicUrl?: string
-    }
-
-export type ResolvedBucket = {
-  name: string
-  backend: ResolvedBackend
-  visibility: 'public' | 'private'
-  access: { create: OperationRule; get: OperationRule; delete: OperationRule }
-  upload?: { maxSizeBytes?: number; accept?: string[] }
-  transforms: boolean
-  readScope?: ScopeResolver
-  writeScope?: ScopeResolver
-  quota?: { perUserBytes?: number; perScopeBytes?: number }
-}
-
-export type ResolvedStorageBuckets = {
-  defaultBucket: string
-  buckets: Map<string, ResolvedBucket>
-}
-
-// ---------------------------------------------------------------------------
-// parseSize
-// ---------------------------------------------------------------------------
-
-const SIZE_UNITS: Record<string, number> = {
-  b: 1,
-  kb: 1024,
-  mb: 1024 * 1024,
-  gb: 1024 * 1024 * 1024,
-}
-
-export function parseSize(value: string | number): number {
-  if (typeof value === 'number') {
-    if (!Number.isFinite(value) || value < 0 || !Number.isInteger(value)) {
-      throw new Error(`[bunderstack] invalid size "${value}"`)
-    }
-    return value
-  }
-
-  const trimmed = value.trim()
-  if (trimmed === '') throw new Error(`[bunderstack] invalid size "${value}"`)
-
-  const match = /^(\d+(?:\.\d+)?)\s*([a-z]*)$/i.exec(trimmed)
-  if (!match) throw new Error(`[bunderstack] invalid size "${value}"`)
-
-  const numStr = match[1]
-  if (numStr === undefined)
-    throw new Error(`[bunderstack] invalid size "${value}"`)
-  const num = parseFloat(numStr)
-  const unit = (match[2] ?? '').toLowerCase()
-
-  if (unit === '') return Math.floor(num)
-
-  const multiplier = SIZE_UNITS[unit]
-  if (multiplier === undefined)
-    throw new Error(`[bunderstack] invalid size "${value}"`)
-
-  return Math.floor(num * multiplier)
-}
-
-// ---------------------------------------------------------------------------
-// Platform override (Bunderhost & co.)
-// ---------------------------------------------------------------------------
-
-/**
- * A deployment platform that injects BUNDERSTACK_S3_ENDPOINT forces every
- * bucket onto that backend — code-level `local`/per-bucket `s3` blocks are
- * ignored so apps deploy unchanged. Logical buckets already prefix object
- * keys ("<bucket>/<uuid>"), so one physical bucket per environment suffices.
- */
-function platformS3Backend(
-  env: Record<string, string | undefined>,
-): ResolvedBackend | undefined {
-  const endpoint = env['BUNDERSTACK_S3_ENDPOINT']
-  if (!endpoint) return undefined
-  return {
-    type: 's3',
-    bucket: env['BUNDERSTACK_S3_BUCKET'] ?? '',
-    region: env['BUNDERSTACK_S3_REGION'] ?? 'auto',
-    endpoint,
-    accessKeyId: env['BUNDERSTACK_S3_ACCESS_KEY_ID'] ?? '',
-    secretAccessKey: env['BUNDERSTACK_S3_SECRET_ACCESS_KEY'] ?? '',
-    publicUrl: env['BUNDERSTACK_S3_PUBLIC_URL'],
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Shared backend resolution
-// ---------------------------------------------------------------------------
-
-function resolveSharedBackend(
-  input: StorageConfigInput | undefined,
-  env: Record<string, string | undefined>,
-): ResolvedBackend {
-  if (!input) return { type: 'local', path: './uploads' }
-
-  if ('local' in input && input.local !== undefined) {
-    return {
-      type: 'local',
-      path: input.local === true ? './uploads' : input.local,
-    }
-  }
-
-  if ('s3' in input && input.s3 !== undefined) {
-    const s3Cfg = typeof input.s3 === 'object' ? input.s3 : {}
-    return {
-      type: 's3',
-      bucket: env['S3_BUCKET'] ?? '',
-      region: env['S3_REGION'] ?? 'us-east-1',
-      endpoint: s3Cfg.endpoint ?? env['S3_ENDPOINT'],
-      accessKeyId: env['S3_ACCESS_KEY_ID'] ?? '',
-      secretAccessKey: env['S3_SECRET_ACCESS_KEY'] ?? '',
-    }
-  }
-
-  return { type: 'local', path: './uploads' }
-}
-
-// ---------------------------------------------------------------------------
-// Per-bucket backend resolution
-// ---------------------------------------------------------------------------
-
-function resolveBucketBackend(
-  bucketInput: BucketConfigInput,
-  sharedBackend: ResolvedBackend,
-  env: Record<string, string | undefined>,
-): ResolvedBackend {
-  // Platform override active → sharedBackend IS the platform backend and
-  // code-level per-bucket backends are ignored.
-  if (env['BUNDERSTACK_S3_ENDPOINT']) return sharedBackend
-  if ('s3' in bucketInput && bucketInput.s3 !== undefined) {
-    const block = bucketInput.s3
-    return {
-      type: 's3',
-      bucket: block.bucket,
-      region: block.region ?? env['S3_REGION'] ?? 'us-east-1',
-      endpoint: block.endpoint ?? env['S3_ENDPOINT'],
-      accessKeyId: env['S3_ACCESS_KEY_ID'] ?? '',
-      secretAccessKey: env['S3_SECRET_ACCESS_KEY'] ?? '',
-      publicUrl: block.publicUrl,
-    }
-  }
-
-  if ('local' in bucketInput && bucketInput.local !== undefined) {
-    return { type: 'local', path: bucketInput.local }
-  }
-
-  return sharedBackend
-}
-
-// ---------------------------------------------------------------------------
-// Bucket resolution
-// ---------------------------------------------------------------------------
-
-function resolveSingleBucket(
-  name: string,
-  input: BucketConfigInput,
-  sharedBackend: ResolvedBackend,
-  env: Record<string, string | undefined>,
-): ResolvedBucket {
-  const visibility = input.visibility ?? 'private'
-  const backend = resolveBucketBackend(input, sharedBackend, env)
-
-  const defaultGet: OperationRule = visibility === 'public' ? 'public' : 'owner'
-
-  const access: ResolvedBucket['access'] = {
-    create: input.access?.create ?? 'authenticated',
-    get: input.access?.get ?? defaultGet,
-    delete: input.access?.delete ?? 'owner',
-  }
-
-  let upload: ResolvedBucket['upload'] | undefined = undefined
-  if (input.upload !== undefined) {
-    upload = {}
-    if (input.upload.maxSize !== undefined) {
-      upload.maxSizeBytes = parseSize(input.upload.maxSize)
-    }
-    if (input.upload.accept !== undefined) {
-      upload.accept = input.upload.accept
-    }
-  }
-
-  let quota: ResolvedBucket['quota'] | undefined = undefined
-  if (input.quota !== undefined) {
-    quota = {}
-    if (input.quota.perUser !== undefined) {
-      quota.perUserBytes = parseSize(input.quota.perUser)
-    }
-    if (input.quota.perScope !== undefined) {
-      quota.perScopeBytes = parseSize(input.quota.perScope)
-    }
-  }
-
-  return {
-    name,
-    backend,
-    visibility,
-    access,
-    upload,
-    transforms: input.transforms ?? false,
-    readScope: input.scope?.read,
-    writeScope: input.scope?.write,
-    quota,
-  }
-}
-
-// ---------------------------------------------------------------------------
-// resolveBuckets
-// ---------------------------------------------------------------------------
-
-export function resolveBuckets(
-  input: StorageConfigInput | undefined,
-  env: Record<string, string | undefined> = process.env,
-): ResolvedStorageBuckets {
-  const sharedBackend =
-    platformS3Backend(env) ?? resolveSharedBackend(input, env)
-  const bucketsInput = input?.buckets
-
-  const declaredNames = bucketsInput ? Object.keys(bucketsInput) : []
-  const defaultBucketName =
-    input?.defaultBucket ??
-    // A single declared bucket is unambiguous — treat it as the default.
-    (declaredNames.length === 1 ? declaredNames[0]! : 'default')
-
-  const buckets = new Map<string, ResolvedBucket>()
-
-  if (!bucketsInput || Object.keys(bucketsInput).length === 0) {
-    // Synthesize a single default bucket
-    const defaultBucket = resolveSingleBucket(
-      defaultBucketName,
-      {},
-      sharedBackend,
-      env,
-    )
-    buckets.set(defaultBucketName, defaultBucket)
-    return { defaultBucket: defaultBucketName, buckets }
-  }
-
-  // Validate defaultBucket is declared
-  if (!(defaultBucketName in bucketsInput)) {
-    throw new Error(
-      `[bunderstack] defaultBucket "${defaultBucketName}" is not a declared bucket`,
-    )
-  }
-
-  for (const [name, bucketInput] of Object.entries(bucketsInput)) {
-    buckets.set(
-      name,
-      resolveSingleBucket(name, bucketInput, sharedBackend, env),
-    )
-  }
-
-  return { defaultBucket: defaultBucketName, buckets }
-}

package/src/storage/delete.ts

@@ -1,26 +0,0 @@
-// src/storage/delete.ts
-import type { AnyDb } from '../dialect'
-import type { StorageAdapter } from './index'
-
-import { deleteFileMetaRow } from './file-meta'
-
-/**
- * Delete a logical file: its transform-cache derivatives (under
- * `${fileId}__transforms/`), the original object, and the file-meta row.
- *
- * All deletion goes through this helper so the model stays addable to a future
- * blob/file split (see file-meta.ts header) — never inline `adapter.delete`.
- */
-export async function deleteFileWithDerivatives(
-  adapter: StorageAdapter,
-  db: AnyDb,
-  fileId: string,
-): Promise<void> {
-  if (adapter.list) {
-    const derivs = await adapter.list(`${fileId}__transforms/`)
-    // Ignore individual derivative-delete errors — orphan sweep is the backstop.
-    await Promise.all(derivs.map((k) => adapter.delete(k).catch(() => {})))
-  }
-  await adapter.delete(fileId)
-  await deleteFileMetaRow(db, fileId)
-}

package/src/storage/file-meta.ts

@@ -1,222 +0,0 @@
-/*
- * DEFERRED — logical/physical blob/file split
- *
- * The current model is 1:1 logical-file = physical-object: one row in
- * bunderstack_file_meta maps to exactly one object in storage. A future
- * blob/file split would introduce:
- *
- *   bunderstackBlob { key, bucket, size, contentType, refcount, createdAt }
- *   bunderstackFile { id, blobKey, ownerId, scopeJson, status, filename,
- *                     createdAt, confirmedAt, deletedAt }
- *
- * This would enable:
- *   - Soft/shadow delete (file.deletedAt + per-bucket retention policy)
- *   - Transfer ownership/scope (mutate file.ownerId / scopeJson, no byte movement)
- *   - Duplicate/share to many users or orgs by reference (refcount++) so sharing
- *     to N users stores bytes once; or by-copy via S3 CopyObject.
- *
- * Deletion would decrement refcount; bytes removed only at 0; orphan sweep also
- * reaps refcount=0 blobs (self-heals crash mid-decrement).
- *
- * Deferred because refcount correctness is a real cost vs. current need.
- *
- * Two forward-compat invariants keep this addable without breaking the public API:
- *   1. fileId is opaque — clients never parse it.
- *   2. All deletion goes through the storage delete helper, never inline.
- *
- * See docs/plans/2026-06-28-multi-bucket-storage-design.md §6 for full rationale.
- */
-
-import { eq, and, lt, sql } from 'drizzle-orm'
-
-import type { ScopeMap } from '../access'
-import type { AnyDb } from '../dialect'
-
-import { rowMatchesScope } from '../access'
-import { bunderstackFiles, filesTableFor } from '../internal-tables'
-
-export type FileMetaRow = typeof bunderstackFiles.$inferSelect
-
-// ─── CRUD ─────────────────────────────────────────────────────────────────────
-
-export async function insertPendingFile(
-  db: AnyDb,
-  input: {
-    fileId: string
-    bucket: string
-    ownerId: string | null
-    scopeJson: string | null
-    filename: string | null
-    contentType: string | null
-  },
-): Promise<void> {
-  const files = filesTableFor(db)
-  await db.insert(files).values({
-    fileId: input.fileId,
-    bucket: input.bucket,
-    ownerId: input.ownerId,
-    scopeJson: input.scopeJson,
-    filename: input.filename,
-    contentType: input.contentType,
-    status: 'pending',
-    createdAt: Date.now(),
-    confirmedAt: null,
-    size: null,
-  })
-}
-
-export async function insertReadyFile(
-  db: AnyDb,
-  input: {
-    fileId: string
-    bucket: string
-    ownerId: string | null
-    scopeJson: string | null
-    filename: string | null
-    contentType: string | null
-    size: number | null
-  },
-): Promise<void> {
-  const files = filesTableFor(db)
-  const now = Date.now()
-  await db.insert(files).values({
-    fileId: input.fileId,
-    bucket: input.bucket,
-    ownerId: input.ownerId,
-    scopeJson: input.scopeJson,
-    filename: input.filename,
-    contentType: input.contentType,
-    size: input.size,
-    status: 'ready',
-    createdAt: now,
-    confirmedAt: now,
-  })
-}
-
-export async function markFileReady(
-  db: AnyDb,
-  fileId: string,
-  patch: { size: number | null; contentType: string | null },
-): Promise<void> {
-  const files = filesTableFor(db)
-  await db
-    .update(files)
-    .set({
-      status: 'ready',
-      confirmedAt: Date.now(),
-      size: patch.size,
-      contentType: patch.contentType,
-    })
-    .where(eq(files.fileId, fileId))
-}
-
-export async function getFileMeta(
-  db: AnyDb,
-  fileId: string,
-): Promise<FileMetaRow | null> {
-  const files = filesTableFor(db)
-  const rows = await db
-    .select()
-    .from(files)
-    .where(eq(files.fileId, fileId))
-    .limit(1)
-  return (rows[0] as FileMetaRow | undefined) ?? null
-}
-
-export async function deleteFileMetaRow(
-  db: AnyDb,
-  fileId: string,
-): Promise<void> {
-  const files = filesTableFor(db)
-  await db.delete(files).where(eq(files.fileId, fileId))
-}
-
-// ─── Sweep ────────────────────────────────────────────────────────────────────
-
-export async function listStalePendingFiles(
-  db: AnyDb,
-  olderThanMs: number,
-): Promise<FileMetaRow[]> {
-  const files = filesTableFor(db)
-  return db
-    .select()
-    .from(files)
-    .where(and(eq(files.status, 'pending'), lt(files.createdAt, olderThanMs)))
-}
-
-// ─── Quota ────────────────────────────────────────────────────────────────────
-
-export async function sumReadySize(
-  db: AnyDb,
-  q: { bucket: string; ownerId?: string; scopeJson?: string },
-): Promise<number> {
-  const files = filesTableFor(db)
-  const conditions = [eq(files.status, 'ready'), eq(files.bucket, q.bucket)]
-  if (q.ownerId !== undefined) {
-    conditions.push(eq(files.ownerId, q.ownerId))
-  }
-  if (q.scopeJson !== undefined) {
-    conditions.push(eq(files.scopeJson, q.scopeJson))
-  }
-
-  const rows = await db
-    .select({
-      total: sql<number>`coalesce(sum(${files.size}), 0)`,
-    })
-    .from(files)
-    .where(and(...conditions))
-
-  const raw = rows[0]?.total ?? 0
-  return Number(raw)
-}
-
-// ─── Scope helpers ────────────────────────────────────────────────────────────
-
-export function scopeToJson(scope: ScopeMap | undefined | null): string | null {
-  if (scope == null) return null
-  const keys = Object.keys(scope)
-  if (keys.length === 0) return null
-  const sorted = keys.sort()
-  const ordered: Record<string, string | string[]> = {}
-  for (const k of sorted) {
-    const value = scope[k]
-    if (value !== undefined) ordered[k] = value
-  }
-  return JSON.stringify(ordered)
-}
-
-function isScopeMap(value: unknown): value is ScopeMap {
-  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
-    return false
-  }
-  for (const item of Object.values(value)) {
-    if (typeof item === 'string') continue
-    if (Array.isArray(item) && item.every((entry) => typeof entry === 'string'))
-      continue
-    return false
-  }
-  return true
-}
-
-export function parseScopeJson(json: string | null): ScopeMap | null {
-  if (json == null) return null
-  try {
-    const parsed = JSON.parse(json)
-    return isScopeMap(parsed) ? parsed : null
-  } catch {
-    // Corrupt/legacy scope_json should not crash a read; treat as no scope.
-    return null
-  }
-}
-
-export function fileMatchesScope(
-  row: FileMetaRow,
-  requesterScope: ScopeMap | undefined,
-): boolean {
-  if (requesterScope == null || Object.keys(requesterScope).length === 0) {
-    return true
-  }
-  if (row.scopeJson == null) return false
-  const parsed = parseScopeJson(row.scopeJson) ?? {}
-  return rowMatchesScope(parsed, requesterScope)
-}

package/src/storage/index.ts

@@ -1,39 +0,0 @@
-// src/storage/index.ts
-import { LocalStorageAdapter } from './local'
-import { S3StorageAdapter } from './s3'
-
-export type { LocalStorageAdapter, S3StorageAdapter }
-export { createStorageOperations } from './operations'
-export type {
-  PrepareUploadResult,
-  StorageDownload,
-  StorageExecutionContext,
-  StorageOperations,
-  StorageOperationsOptions,
-} from './operations'
-
-export interface PresignPutOptions {
-  contentType?: string
-  expiresIn: number
-}
-export interface PresignGetOptions {
-  expiresIn: number
-}
-
-export interface StorageAdapter {
-  upload(
-    fileId: string,
-    data: Blob | ArrayBuffer,
-    contentType: string,
-  ): Promise<void>
-  get(fileId: string): Promise<Response>
-  delete(fileId: string): Promise<void>
-  exists(fileId: string): Promise<boolean>
-  // Optional — present on S3, absent on local (router uses proxy path for local)
-  presignPut?(key: string, opts: PresignPutOptions): Promise<string>
-  presignGet?(key: string, opts: PresignGetOptions): Promise<string>
-  stat?(key: string): Promise<{ size: number; contentType: string } | null>
-  publicUrlFor?(key: string): string | undefined
-  /** List full object keys under a prefix (used to reap transform derivatives). */
-  list?(prefix: string): Promise<string[]>
-}

package/src/storage/local.ts

@@ -1,69 +0,0 @@
-// src/storage/local.ts
-import { mkdir, readdir } from 'node:fs/promises'
-import { join } from 'node:path'
-
-export class LocalStorageAdapter {
-  private readonly basePath: string
-  constructor(basePath: string) {
-    this.basePath = basePath
-  }
-
-  private filePath(fileId: string) {
-    return join(this.basePath, fileId)
-  }
-
-  async upload(
-    fileId: string,
-    data: Blob | ArrayBuffer,
-    contentType: string,
-  ): Promise<void> {
-    await mkdir(this.basePath, { recursive: true })
-    const bytes = data instanceof Blob ? await data.arrayBuffer() : data
-    await Bun.write(
-      Bun.file(this.filePath(fileId), { type: contentType }),
-      bytes,
-    )
-  }
-
-  async get(fileId: string): Promise<Response> {
-    const file = Bun.file(this.filePath(fileId))
-    if (!(await file.exists()))
-      return new Response('Not found', { status: 404 })
-    return new Response(file, {
-      headers: {
-        'Content-Type': file.type,
-        'Cache-Control': 'public, max-age=31536000',
-      },
-    })
-  }
-
-  async delete(fileId: string): Promise<void> {
-    const file = Bun.file(this.filePath(fileId))
-    if (await file.exists()) await file.unlink()
-  }
-
-  async exists(fileId: string): Promise<boolean> {
-    return Bun.file(this.filePath(fileId)).exists()
-  }
-
-  async stat(
-    key: string,
-  ): Promise<{ size: number; contentType: string } | null> {
-    const file = Bun.file(this.filePath(key))
-    if (!(await file.exists())) return null
-    return { size: file.size, contentType: file.type }
-  }
-
-  async list(prefix: string): Promise<string[]> {
-    const cleanPrefix = prefix.replace(/\/$/, '')
-    const dir = join(this.basePath, cleanPrefix)
-    let entries: string[]
-    try {
-      entries = await readdir(dir)
-    } catch {
-      // Missing dir (or prefix isn't a directory) → no derivatives.
-      return []
-    }
-    return entries.map((name) => `${cleanPrefix}/${name}`)
-  }
-}