@softize/opus 8.6.6

package/src/server/drivers/node.ts

@@ -0,0 +1,386 @@
+/**
+ * @softize/opus/server/node — driver connect/node-http
+ *
+ * Implementa `ServerAdapter` sobre `IncomingMessage`/`ServerResponse` puros,
+ * sem framework: rotas vivem numa Map interna e o `handler` resultante encaixa
+ * em qualquer stack connect-style (middlewares do vite, express, ou um
+ * `http.createServer` direto). É o driver que o `opusDesign()` usa pra servir
+ * `/api` in-process no preview de design.
+ *
+ * Uso:
+ *   import http from 'node:http'
+ *   import { createRuntime } from '@softize/opus/core'
+ *   import { nodeServer } from '@softize/opus/server/node'
+ *
+ *   const node = nodeServer()
+ *   const runtime = createRuntime({ server: node.adapter, auth: ... })
+ *   runtime.register([...])
+ *   await runtime.start()
+ *   http.createServer(node.handler).listen(3000)
+ *
+ * Semântica do `handler`:
+ *   - rota montada (actions sob `apiPrefix` + endpoints) → responde;
+ *   - path sob `apiPrefix` sem rota → 404 em envelope opus;
+ *   - fora do `apiPrefix` → `next()` quando fornecido, senão 404 em envelope.
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type {
+  ActionDef,
+  ActionResult,
+  ContextBase,
+  EndpointSpec,
+  ErrorInput,
+  RuntimeRef,
+  ServerAdapter,
+} from '../../core/index.ts'
+import { error } from '../../core/index.ts'
+import {
+  toOpenAPISpec,
+  type OpenAPIInfo,
+  type OpenAPIServer,
+} from '../../schema/openapi.ts'
+import {
+  httpStatusFor,
+  inputSourceFor,
+  methodFor,
+  pathFor,
+  serializeResult,
+  shouldMountPublicly,
+  successStatusFor,
+} from '../index.ts'
+
+// =============================================================================
+// Options
+// =============================================================================
+
+export interface NodeServerOptions {
+  /** Prefixo do path. Default '/api'. */
+  apiPrefix?: string
+
+  /**
+   * Endpoints (health/ready/openapi) montados automaticamente no `init` do
+   * runtime. Equivale a chamar `adapter.mountEndpoints(spec)` após o start.
+   */
+  endpoints?: EndpointSpec
+
+  /**
+   * Info do OpenAPI document (title, version, description). Quando ausente,
+   * usa um default genérico — sobrescreva pra publicar API decente.
+   */
+  openapiInfo?: OpenAPIInfo
+
+  /** Servers do OpenAPI document. */
+  openapiServers?: OpenAPIServer[]
+}
+
+export interface NodeServerHandle {
+  /** Vai no `createRuntime({ server })`. */
+  adapter: ServerAdapter
+
+  /** Middleware connect-style: pluga em vite/express/http.createServer. */
+  handler: (req: IncomingMessage, res: ServerResponse, next?: () => void) => void
+
+  /** True se há rota montada pra `method` + `pathname` (actions e endpoints).
+   *  Deixa quem embala (ex.: opusDesign) distinguir 404 de rota antes de delegar. */
+  hasRoute: (method: string, pathname: string) => boolean
+}
+
+// =============================================================================
+// Factory
+// =============================================================================
+
+type RouteFn = (req: IncomingMessage, res: ServerResponse, url: URL) => Promise<void>
+
+export function nodeServer(options: NodeServerOptions = {}): NodeServerHandle {
+  const {
+    apiPrefix = '/api',
+    endpoints,
+    openapiInfo = { title: 'tbdlib API', version: '0.0.0' },
+    openapiServers,
+  } = options
+
+  let runtime: RuntimeRef | undefined
+  const routes = new Map<string, RouteFn>()
+  const mountedActions: ActionDef[] = []
+
+  const requireRuntime = (): RuntimeRef => {
+    /* v8 ignore next 3 — defensivo; init() é sempre chamado antes de mount/etc */
+    if (runtime === undefined) {
+      throw new Error('nodeServer: runtime not initialized (init not called)')
+    }
+    return runtime
+  }
+
+  const mountEndpoints = (spec: EndpointSpec): void => {
+    mountHealth(routes, spec)
+    mountReady(routes, spec, requireRuntime)
+    mountOpenAPI(routes, spec, mountedActions, {
+      info: openapiInfo,
+      ...(openapiServers !== undefined ? { servers: openapiServers } : {}),
+      apiPrefix,
+    })
+  }
+
+  const adapter: ServerAdapter = {
+    name: 'node',
+    kind: 'server',
+
+    init(rt) {
+      runtime = rt
+      if (endpoints !== undefined) mountEndpoints(endpoints)
+    },
+
+    mount(action) {
+      if (!shouldMountPublicly(action)) return
+      mountedActions.push(action)
+
+      const method = methodFor(action)
+      const path = pathFor(action, apiPrefix)
+      const source = inputSourceFor(action)
+
+      routes.set(`${method} ${path}`, async (req, res, url) => {
+        const rt = requireRuntime()
+        const requestId = crypto.randomUUID()
+        const ctx = await resolveCtx(rt, req, requestId)
+
+        let input: unknown
+        if (source === 'body') {
+          const raw = await readBody(req)
+          // Body vazio vira `undefined` — o schema de input da action decide.
+          if (raw.length === 0) {
+            input = undefined
+          } else {
+            try {
+              input = JSON.parse(raw)
+            } catch {
+              sendResult(
+                res,
+                400,
+                driverResult(
+                  { code: 'server.invalid_json', category: 'validation', message: 'Request body is not valid JSON' },
+                  action.name,
+                  requestId,
+                ),
+              )
+              return
+            }
+          }
+        } else {
+          // Strings cruas, mesma semântica do `req.query` do fastify — paridade
+          // com prod; os contratos coagem (z.coerce etc).
+          input = Object.fromEntries(url.searchParams)
+        }
+
+        const result = await rt.execute(action.name, input, ctx)
+        const status = result.ok
+          ? successStatusFor(action)
+          : httpStatusFor(result.error)
+
+        sendResult(res, status, result)
+      })
+    },
+
+    mountEndpoints,
+  }
+
+  const handler = (
+    req: IncomingMessage,
+    res: ServerResponse,
+    next?: () => void,
+  ): void => {
+    const url = new URL(req.url ?? '/', 'http://localhost')
+    const route = routes.get(`${req.method ?? 'GET'} ${url.pathname}`)
+
+    if (route !== undefined) {
+      route(req, res, url).catch((err) => {
+        /* v8 ignore next 7 — defensivo; execute() não lança (devolve envelope) */
+        sendResult(
+          res,
+          500,
+          driverResult(
+            { code: 'server.unhandled', category: 'internal', message: String(err) },
+            deriveActionName(url.pathname, apiPrefix),
+            crypto.randomUUID(),
+          ),
+        )
+      })
+      return
+    }
+
+    if (url.pathname === apiPrefix || url.pathname.startsWith(`${apiPrefix}/`)) {
+      sendResult(res, 404, routeNotFound(url.pathname, apiPrefix))
+      return
+    }
+
+    if (next !== undefined) {
+      next()
+      return
+    }
+    sendResult(res, 404, routeNotFound(url.pathname, apiPrefix))
+  }
+
+  return {
+    adapter,
+    handler,
+    hasRoute: (method, pathname) => routes.has(`${method} ${pathname}`),
+  }
+}
+
+// =============================================================================
+// Context resolution
+// =============================================================================
+
+async function resolveCtx(
+  rt: RuntimeRef,
+  req: IncomingMessage,
+  requestId: string,
+): Promise<ContextBase> {
+  const base = await resolveAuthBase(rt, req)
+  return {
+    ...base,
+    requestId,
+    provenance: {
+      kind: 'http',
+      userId: base.user?.id ?? null,
+      requestId,
+    },
+  }
+}
+
+async function resolveAuthBase(
+  rt: RuntimeRef,
+  req: IncomingMessage,
+): Promise<{ user: ContextBase['user']; tenantId: string | null; can: ContextBase['can'] }> {
+  if (rt.auth === undefined) {
+    return { user: null, tenantId: null, can: () => false }
+  }
+  const resolved = await rt.auth.resolveContext(req)
+  return {
+    user: resolved.user,
+    tenantId: resolved.tenantId ?? null,
+    can: resolved.can,
+  }
+}
+
+// =============================================================================
+// Request/response plumbing
+// =============================================================================
+
+async function readBody(req: IncomingMessage): Promise<string> {
+  // setEncoding evita quebrar UTF-8 multi-byte na fronteira de chunks.
+  req.setEncoding('utf8')
+  let body = ''
+  for await (const chunk of req) body += chunk as string
+  return body
+}
+
+function sendResult(res: ServerResponse, status: number, result: ActionResult<unknown>): void {
+  res.statusCode = status
+  res.setHeader('content-type', 'application/json; charset=utf-8')
+  res.end(JSON.stringify(serializeResult(result)))
+}
+
+/**
+ * Envelope de erro produzido pelo DRIVER (sem passar pelo execute). Carrega
+ * `meta` completo — o fetch client só reconhece envelope com `meta` presente.
+ */
+function driverResult(
+  input: ErrorInput,
+  action: string,
+  requestId: string,
+): ActionResult<never> {
+  return {
+    ok: false,
+    error: error(input),
+    meta: { actionId: crypto.randomUUID(), action, durationMs: 0, requestId },
+  }
+}
+
+function routeNotFound(pathname: string, apiPrefix: string): ActionResult<never> {
+  return driverResult(
+    { code: 'server.route_not_found', category: 'not_found', message: `No route for ${pathname}` },
+    deriveActionName(pathname, apiPrefix),
+    crypto.randomUUID(),
+  )
+}
+
+/** Nome de action derivado do path (pro `meta.action` de erros do driver). */
+function deriveActionName(pathname: string, apiPrefix: string): string {
+  if (pathname !== apiPrefix && !pathname.startsWith(`${apiPrefix}/`)) return 'unknown'
+  const name = pathname
+    .slice(apiPrefix.length)
+    .replace(/^\/+/, '')
+    .split('/')
+    .map(decodeURIComponent)
+    .join('.')
+  return name.length > 0 ? name : 'unknown'
+}
+
+// =============================================================================
+// Endpoints
+// =============================================================================
+
+function mountHealth(routes: Map<string, RouteFn>, spec: EndpointSpec): void {
+  const cfg = spec.health
+  if (cfg === false) return
+  const path = pathFromSpec(cfg, '/health')
+  routes.set(`GET ${path}`, async (_req, res) => {
+    sendJson(res, 200, { ok: true })
+  })
+}
+
+function mountReady(
+  routes: Map<string, RouteFn>,
+  spec: EndpointSpec,
+  getRuntime: () => RuntimeRef,
+): void {
+  const cfg = spec.ready
+  if (cfg === false) return
+  const path = pathFromSpec(cfg, '/ready')
+  routes.set(`GET ${path}`, async (_req, res) => {
+    const status = await getRuntime().healthCheck()
+    sendJson(res, status.ok ? 200 : 503, status)
+  })
+}
+
+function pathFromSpec(
+  cfg: boolean | { path?: string } | undefined,
+  fallback: string,
+): string {
+  if (typeof cfg === 'object' && cfg.path !== undefined) return cfg.path
+  return fallback
+}
+
+function mountOpenAPI(
+  routes: Map<string, RouteFn>,
+  spec: EndpointSpec,
+  actions: ActionDef[],
+  options: {
+    info: OpenAPIInfo
+    servers?: OpenAPIServer[]
+    apiPrefix: string
+  },
+): void {
+  const cfg = spec.openapi
+  if (cfg === false) return
+  const path =
+    typeof cfg === 'object' && cfg.path !== undefined ? cfg.path : '/openapi.json'
+  routes.set(`GET ${path}`, async (_req, res) => {
+    sendJson(
+      res,
+      200,
+      toOpenAPISpec(actions, {
+        info: options.info,
+        ...(options.servers !== undefined ? { servers: options.servers } : {}),
+        apiPrefix: options.apiPrefix,
+      }),
+    )
+  })
+}
+
+function sendJson(res: ServerResponse, status: number, body: unknown): void {
+  res.statusCode = status
+  res.setHeader('content-type', 'application/json; charset=utf-8')
+  res.end(JSON.stringify(body))
+}

package/src/server/index.ts

@@ -0,0 +1,142 @@
+/**
+ * @softize/opus/server — shared helpers for server drivers.
+ *
+ * Drivers (Fastify, Hono, etc) consomem este módulo pra:
+ *   - mapear ActionError.category → HTTP status
+ *   - derivar route path + method de uma ActionDef
+ *   - serializar ActionResult em response body
+ *
+ * Lógica específica de driver (registro de rotas, parsing de request) vive
+ * em `src/drivers/<driver>.ts`.
+ */
+
+import type {
+  ActionDef,
+  ActionError,
+  ActionResult,
+  ErrorCategory,
+} from '../core/index.ts'
+
+// =============================================================================
+// HTTP status mapping
+// =============================================================================
+
+/**
+ * Mapping default `ErrorCategory` → HTTP status code.
+ * Ver §3 do protocolo.
+ */
+const DEFAULT_HTTP_STATUS: Record<ErrorCategory, number> = {
+  validation: 400,
+  authentication: 401,
+  authorization: 403,
+  not_found: 404,
+  conflict: 409,
+  rate_limit: 429,
+  dependency: 502,
+  internal: 500,
+}
+
+/**
+ * Retorna o HTTP status code apropriado pra um `ActionError`.
+ */
+export function httpStatusFor(error: ActionError): number {
+  return DEFAULT_HTTP_STATUS[error.category]
+}
+
+/**
+ * Retorna o HTTP status pra success result. Default 200; action pode
+ * declarar `successStatus` (ex: 201 pra create).
+ */
+export function successStatusFor(action: ActionDef): number {
+  return action.successStatus ?? 200
+}
+
+// =============================================================================
+// Route convention
+// =============================================================================
+
+/**
+ * Método HTTP padrão por kind:
+ *   - simple, form → POST (mutações tipicamente)
+ *   - search, view → GET (leitura)
+ */
+export type HttpMethod = 'GET' | 'POST'
+
+export function methodFor(action: ActionDef): HttpMethod {
+  return action.kind === 'simple' || action.kind === 'form' ? 'POST' : 'GET'
+}
+
+/**
+ * Path derivado do nome da action. Converte dots em segments.
+ *   - 'deal.archive'        → '/deal/archive'
+ *   - 'crm.deal.list'       → '/crm/deal/list'
+ *   - 'auth.sessionRefresh' → '/auth/sessionRefresh'
+ *
+ * `prefix` adicionado se passado (default '/api').
+ */
+export function pathFor(action: ActionDef, prefix = '/api'): string {
+  const segments = action.name.split('.').map(encodeURIComponent)
+  return `${prefix}/${segments.join('/')}`
+}
+
+// =============================================================================
+// Body shape
+// =============================================================================
+
+/**
+ * Decide se o input vem do body (POST) ou query string (GET).
+ * Drivers usam pra extrair input do request.
+ */
+export function inputSourceFor(action: ActionDef): 'body' | 'query' {
+  return methodFor(action) === 'POST' ? 'body' : 'query'
+}
+
+// =============================================================================
+// Result serialization
+// =============================================================================
+
+/**
+ * Envelope JSON-serializável de `ActionResult`. Driver chama `JSON.stringify`
+ * direto no retorno desta função.
+ *
+ * `cause` em error é serializado como string (ver §3 do protocolo).
+ */
+export function serializeResult<T>(result: ActionResult<T>): unknown {
+  if (result.ok) {
+    return { ok: true, data: result.data, meta: result.meta }
+  }
+  return {
+    ok: false,
+    error: serializeError(result.error),
+    meta: result.meta,
+  }
+}
+
+function serializeError(err: ActionError): Record<string, unknown> {
+  const out: Record<string, unknown> = {
+    code: err.code,
+    category: err.category,
+    message: err.message,
+    severity: err.severity,
+    retriable: err.retriable,
+  }
+  if (err.i18nKey !== undefined) out.i18nKey = err.i18nKey
+  if (err.i18nParams !== undefined) out.i18nParams = err.i18nParams
+  if (err.field !== undefined) out.field = err.field
+  if (err.issues !== undefined) out.issues = err.issues
+  if (err.cause !== undefined) out.cause = String(err.cause)
+  if (err.meta !== undefined) out.meta = err.meta
+  return out
+}
+
+// =============================================================================
+// Internal action filter
+// =============================================================================
+
+/**
+ * Actions com `internal: true` não são expostas via REST público.
+ * Driver checa antes de chamar mount().
+ */
+export function shouldMountPublicly(action: ActionDef): boolean {
+  return action.internal !== true
+}

package/src/storage/drivers/fs.ts

@@ -0,0 +1,90 @@
+/**
+ * @softize/opus/storage/fs — driver de disco local (EXPERIMENTAL).
+ *
+ * Guarda cada objeto como arquivo sob `root` (a key vira o caminho relativo) e o
+ * `contentType` num sidecar `<arquivo>.meta.json` (o filesystem não tem metadata).
+ * Pra dev e single-host; produção multi-host prefere `storage/s3`.
+ *
+ * `url()` exige `baseUrl` (o app serve o `root` estaticamente por conta própria —
+ * o driver não sobe servidor): sem `baseUrl`, url() falha explicando.
+ */
+
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+
+import type { StorageAdapter, StorageObject, StoragePutOptions } from '../../core/index.ts'
+import { normalizeKey } from '../index.ts'
+
+export interface FsStorageOptions {
+  /** Diretório raiz dos objetos (criado sob demanda). */
+  root: string
+  /** Base pública de `url()` (ex.: `https://app.exemplo.com/arquivos`). Sem ela, url() falha. */
+  baseUrl?: string
+  /** Nome do adapter (default 'fs'). */
+  name?: string
+}
+
+/** Sidecar de metadata: `<arquivo>.meta.json` ao lado do objeto. */
+function metaPathOf(filePath: string): string {
+  return `${filePath}.meta.json`
+}
+
+export function fsStorage(options: FsStorageOptions): StorageAdapter {
+  const root = path.resolve(options.root)
+  const baseUrl = options.baseUrl?.replace(/\/+$/, '')
+
+  // normalizeKey barra traversal/absoluto; o resolve + guard abaixo é o cinto extra.
+  function filePathOf(key: string): string {
+    const full = path.resolve(root, normalizeKey(key))
+    if (!full.startsWith(`${root}${path.sep}`)) {
+      throw new Error(`Key de storage fora do root: "${key}".`)
+    }
+    return full
+  }
+
+  return {
+    name: options.name ?? 'fs',
+    kind: 'storage',
+
+    async put(key: string, data: Uint8Array, opts?: StoragePutOptions): Promise<void> {
+      const file = filePathOf(key)
+      await fs.mkdir(path.dirname(file), { recursive: true })
+      await fs.writeFile(file, data)
+      if (opts?.contentType !== undefined) {
+        await fs.writeFile(metaPathOf(file), JSON.stringify({ contentType: opts.contentType }))
+      }
+    },
+
+    async get(key: string): Promise<StorageObject | null> {
+      const file = filePathOf(key)
+      let data: Buffer
+      try {
+        data = await fs.readFile(file)
+      } catch {
+        return null
+      }
+      let contentType: string | undefined
+      try {
+        const meta = JSON.parse(await fs.readFile(metaPathOf(file), 'utf8')) as { contentType?: string }
+        contentType = meta.contentType
+      } catch {
+        /* Sem sidecar → sem contentType. */
+      }
+      return { data: new Uint8Array(data), ...(contentType !== undefined ? { contentType } : {}) }
+    },
+
+    async delete(key: string): Promise<void> {
+      const file = filePathOf(key)
+      await fs.rm(file, { force: true })
+      await fs.rm(metaPathOf(file), { force: true })
+    },
+
+    async url(key: string): Promise<string> {
+      const k = normalizeKey(key)
+      if (baseUrl === undefined) {
+        throw new Error('fsStorage sem baseUrl — configure-a (e sirva o root) ou use storage/s3 pra URL assinada.')
+      }
+      return `${baseUrl}/${k}`
+    },
+  }
+}