@atomservice/functions-sdk 0.1.6

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@atomservice/functions-sdk",
+  "version": "0.1.6",
+  "description": "函数作者 SDK：定义器（defineFunction 等）、event 类型推导、schema 校验、结构化日志、内置 HTTP 运行时",
+  "type": "module",
+  "author": "openorson",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openorson/atomservice.git",
+    "directory": "services/functions/sdk"
+  },
+  "bugs": "https://github.com/openorson/atomservice/issues",
+  "homepage": "https://github.com/openorson/atomservice/tree/main/services/functions/sdk#readme",
+  "keywords": [
+    "atomservice",
+    "functions",
+    "faas",
+    "sdk",
+    "bun"
+  ],
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "typebox": "1.2.2"
+  },
+  "devDependencies": {
+    "typescript": "^6"
+  }
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+export {
+  defineAsyncFunction,
+  defineAsyncStreamFunction,
+  defineFunction,
+  defineStreamFunction,
+} from "./sdk.define.ts"
+export type {
+  BusinessErrorPayload,
+  ErrorPayload,
+  ResultEnvelope,
+  SystemErrorPayload,
+} from "./sdk.errors.ts"
+export { BusinessError, isBusinessError, isSystemError, SystemError } from "./sdk.errors.ts"
+export type { LogContext, LogLevel, LogRecord, LogSink } from "./sdk.log.ts"
+export { createLogger, stdoutSink } from "./sdk.log.ts"
+export type { ServeOptions } from "./sdk.runtime.ts"
+export { serve } from "./sdk.runtime.ts"
+export type {
+  AnyFunctionDefinition,
+  AsyncFunctionDefinition,
+  AsyncStreamFunctionDefinition,
+  DeepPartial,
+  ErrorsSchema,
+  ExecutionMode,
+  FunctionConfig,
+  FunctionContext,
+  FunctionDefinition,
+  FunctionKind,
+  FunctionRegistry,
+  LogFields,
+  Logger,
+  StreamFunctionDefinition,
+} from "./sdk.types.ts"

package/src/sdk.consts.ts

@@ -0,0 +1,15 @@
+export const INVOKE_PATH_PREFIX = "/__invoke/"
+export const HEALTH_PATH = "/__health"
+export const DEFAULT_BUNDLE_PORT = 8080
+export const REQUEST_ID_HEADER = "x-atomfn-request-id"
+
+export const SYSTEM_ERROR = {
+  NOT_FOUND: "NOT_FOUND",
+  VALIDATION_FAILED: "VALIDATION_FAILED",
+  OUTPUT_INVALID: "OUTPUT_INVALID",
+  FUNCTION_ERROR: "FUNCTION_ERROR",
+  FUNCTION_TIMEOUT: "FUNCTION_TIMEOUT",
+  OVERLOADED: "OVERLOADED",
+} as const
+
+export type SystemErrorCode = (typeof SYSTEM_ERROR)[keyof typeof SYSTEM_ERROR]

package/src/sdk.consumer.ts

@@ -0,0 +1,170 @@
+import { SQL } from "bun"
+import type { ContextFactory } from "./sdk.executor.ts"
+import { type RawOutcome, runOneShot, runStream } from "./sdk.run.ts"
+import type { AnyFunctionDefinition, FunctionRegistry } from "./sdk.types.ts"
+import { validate } from "./sdk.validate.ts"
+
+export interface ConsumerOptions {
+  databaseUrl: string
+  project: string
+  bundle: string
+  registry: FunctionRegistry
+  makeContext: ContextFactory
+  pollIntervalMs?: number
+  visibilityTimeoutSec?: number
+}
+
+interface ClaimedJob {
+  id: string
+  fn: string
+  event: unknown
+  webhook: string | null
+  attempts: number
+  maxAttempts: number
+}
+
+function isAsyncKind(def: AnyFunctionDefinition): boolean {
+  return def.kind === "asyncFunction" || def.kind === "asyncStreamFunction"
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function deepMerge(target: unknown, patch: unknown): unknown {
+  if (!isPlainObject(target) || !isPlainObject(patch)) return patch
+  const result: Record<string, unknown> = { ...target }
+  for (const [key, value] of Object.entries(patch)) {
+    result[key] = isPlainObject(result[key]) && isPlainObject(value) ? deepMerge(result[key], value) : value
+  }
+  return result
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+export function startConsumer(options: ConsumerOptions): () => void {
+  const asyncNames = Object.entries(options.registry)
+    .filter(([, def]) => isAsyncKind(def))
+    .map(([name]) => name)
+  if (asyncNames.length === 0) return () => {}
+
+  const sql = new SQL(options.databaseUrl)
+  const interval = options.pollIntervalMs ?? 1000
+  const visibilitySec = options.visibilityTimeoutSec ?? 300
+  const asyncNamesLiteral = `{${asyncNames.join(",")}}`
+  let stopped = false
+
+  async function claim(): Promise<ClaimedJob | null> {
+    const rows = (await sql`
+      UPDATE "Job" SET status = 'running', "lockedAt" = now(), attempts = attempts + 1, "updatedAt" = now()
+      WHERE id = (
+        SELECT id FROM "Job"
+        WHERE project = ${options.project} AND bundle = ${options.bundle}
+          AND fn = ANY(${asyncNamesLiteral}::text[])
+          AND "availableAt" <= now()
+          AND (
+            status = 'queued'
+            OR (status = 'running' AND "lockedAt" < now() - make_interval(secs => ${visibilitySec}))
+          )
+        ORDER BY "availableAt"
+        FOR UPDATE SKIP LOCKED LIMIT 1
+      )
+      RETURNING id, fn, event, webhook, attempts, "maxAttempts"
+    `) as ClaimedJob[]
+    return rows[0] ?? null
+  }
+
+  async function execute(job: ClaimedJob): Promise<RawOutcome> {
+    const def = options.registry[job.fn]
+    if (!def) return { kind: "crash", message: `未注册函数 ${job.fn}` }
+    const ctx = options.makeContext(job.fn, job.id)
+
+    const rawEvent = typeof job.event === "string" ? JSON.parse(job.event) : job.event
+    const parsed = validate(def.input, rawEvent)
+    if (!parsed.ok) return { kind: "crash", message: `入参校验失败：${parsed.issues.join("; ")}` }
+    const event = parsed.value
+
+    if (def.kind === "asyncStreamFunction") {
+      const generator = runStream(def, event, ctx)
+      let merged: unknown = {}
+      while (true) {
+        const next = await generator.next()
+        if (next.done) {
+          if (next.value.kind === "ok") return { kind: "ok", data: merged }
+          return next.value
+        }
+        merged = deepMerge(merged, next.value)
+      }
+    }
+    return runOneShot(def, event, ctx)
+  }
+
+  async function finalize(job: ClaimedJob, outcome: RawOutcome): Promise<void> {
+    if (outcome.kind === "ok") {
+      await sql`UPDATE "Job" SET status = 'done', result = ${JSON.stringify(outcome.data ?? null)}::jsonb, error = NULL, "updatedAt" = now() WHERE id = ${job.id}`
+      await notify(job, "done")
+      return
+    }
+
+    if (outcome.kind === "business") {
+      const error = { type: "business", code: outcome.code, data: outcome.data }
+      await sql`UPDATE "Job" SET status = 'failed', error = ${JSON.stringify(error)}::jsonb, "updatedAt" = now() WHERE id = ${job.id}`
+      await notify(job, "failed")
+      return
+    }
+
+    const error = { type: "system", code: "FUNCTION_ERROR", message: outcome.message, retryable: true }
+    if (job.attempts < job.maxAttempts) {
+      const backoffSec = Math.min(2 ** job.attempts, 300)
+      await sql`UPDATE "Job" SET status = 'queued', error = ${JSON.stringify(error)}::jsonb, "lockedAt" = NULL, "availableAt" = now() + make_interval(secs => ${backoffSec}), "updatedAt" = now() WHERE id = ${job.id}`
+      return
+    }
+    await sql`UPDATE "Job" SET status = 'failed', error = ${JSON.stringify(error)}::jsonb, "updatedAt" = now() WHERE id = ${job.id}`
+    await notify(job, "failed")
+  }
+
+  async function notify(job: ClaimedJob, status: "done" | "failed"): Promise<void> {
+    if (!job.webhook) return
+    await fetch(job.webhook, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ jobId: job.id, status }),
+    }).catch(() => {})
+  }
+
+  const heartbeatIntervalMs = Math.floor((visibilitySec / 3) * 1000)
+
+  function startHeartbeat(jobId: string): () => void {
+    const timer = setInterval(() => {
+      sql`UPDATE "Job" SET "lockedAt" = now() WHERE id = ${jobId} AND status = 'running'`.catch(() => {})
+    }, heartbeatIntervalMs)
+    return () => clearInterval(timer)
+  }
+
+  async function loop(): Promise<void> {
+    while (!stopped) {
+      let job: ClaimedJob | null = null
+      try {
+        job = await claim()
+      } catch {
+        await sleep(interval)
+        continue
+      }
+      if (!job) {
+        await sleep(interval)
+        continue
+      }
+      const stopHeartbeat = startHeartbeat(job.id)
+      const outcome = await execute(job)
+      stopHeartbeat()
+      await finalize(job, outcome).catch(() => {})
+    }
+  }
+
+  void loop()
+  return () => {
+    stopped = true
+  }
+}

package/src/sdk.context.ts

@@ -0,0 +1,25 @@
+import { BusinessError } from "./sdk.errors.ts"
+import { createLogger, type LogSink } from "./sdk.log.ts"
+import type { ErrorsSchema, FunctionContext } from "./sdk.types.ts"
+
+export interface ContextInput {
+  project: string
+  bundle: string
+  function: string
+  requestId: string
+  sink: LogSink
+}
+
+export function createContext<TErrors extends ErrorsSchema>(input: ContextInput): FunctionContext<TErrors> {
+  const log = createLogger(
+    { project: input.project, bundle: input.bundle, function: input.function, requestId: input.requestId },
+    input.sink,
+  )
+  return {
+    requestId: input.requestId,
+    log,
+    error(code, data) {
+      return new BusinessError(code, data)
+    },
+  }
+}

package/src/sdk.define.ts

@@ -0,0 +1,91 @@
+import type { Static, TSchema } from "typebox"
+import type {
+  AsyncFunctionDefinition,
+  AsyncStreamFunctionDefinition,
+  DeepPartial,
+  ErrorsSchema,
+  FunctionConfig,
+  FunctionContext,
+  FunctionDefinition,
+  StreamFunctionDefinition,
+} from "./sdk.types.ts"
+
+interface OneShotInput<TInput extends TSchema, TOutput extends TSchema, TErrors extends ErrorsSchema> {
+  input: TInput
+  output: TOutput
+  errors?: TErrors
+  config?: FunctionConfig
+  handler: (event: Static<TInput>, ctx: FunctionContext<TErrors>) => Bun.MaybePromise<Static<TOutput>>
+}
+
+interface StreamInput<TInput extends TSchema, TOutput extends TSchema, TErrors extends ErrorsSchema> {
+  input: TInput
+  output: TOutput
+  errors?: TErrors
+  config?: FunctionConfig
+  handler: (
+    event: Static<TInput>,
+    ctx: FunctionContext<TErrors>,
+  ) => AsyncGenerator<DeepPartial<Static<TOutput>>, void, void>
+}
+
+const EMPTY_ERRORS = {} as ErrorsSchema
+const EMPTY_CONFIG: FunctionConfig = {}
+
+export function defineFunction<TInput extends TSchema, TOutput extends TSchema, const TErrors extends ErrorsSchema>(
+  def: OneShotInput<TInput, TOutput, TErrors>,
+): FunctionDefinition<TInput, TOutput, TErrors> {
+  return {
+    kind: "function",
+    input: def.input,
+    output: def.output,
+    errors: (def.errors ?? EMPTY_ERRORS) as TErrors,
+    config: def.config ?? EMPTY_CONFIG,
+    handler: def.handler,
+  }
+}
+
+export function defineStreamFunction<
+  TInput extends TSchema,
+  TOutput extends TSchema,
+  const TErrors extends ErrorsSchema,
+>(def: StreamInput<TInput, TOutput, TErrors>): StreamFunctionDefinition<TInput, TOutput, TErrors> {
+  return {
+    kind: "streamFunction",
+    input: def.input,
+    output: def.output,
+    errors: (def.errors ?? EMPTY_ERRORS) as TErrors,
+    config: def.config ?? EMPTY_CONFIG,
+    handler: def.handler,
+  }
+}
+
+export function defineAsyncFunction<
+  TInput extends TSchema,
+  TOutput extends TSchema,
+  const TErrors extends ErrorsSchema,
+>(def: OneShotInput<TInput, TOutput, TErrors>): AsyncFunctionDefinition<TInput, TOutput, TErrors> {
+  return {
+    kind: "asyncFunction",
+    input: def.input,
+    output: def.output,
+    errors: (def.errors ?? EMPTY_ERRORS) as TErrors,
+    config: def.config ?? EMPTY_CONFIG,
+    handler: def.handler,
+  }
+}
+
+export function defineAsyncStreamFunction<
+  TInput extends TSchema,
+  TOutput extends TSchema,
+  const TErrors extends ErrorsSchema,
+>(def: StreamInput<TInput, TOutput, TErrors>): AsyncStreamFunctionDefinition<TInput, TOutput, TErrors> {
+  return {
+    kind: "asyncStreamFunction",
+    input: def.input,
+    output: def.output,
+    errors: (def.errors ?? EMPTY_ERRORS) as TErrors,
+    config: def.config ?? EMPTY_CONFIG,
+    handler: def.handler,
+  }
+}

package/src/sdk.errors.ts

@@ -0,0 +1,56 @@
+export interface BusinessErrorPayload {
+  type: "business"
+  code: string
+  data: unknown
+}
+
+export interface SystemErrorPayload {
+  type: "system"
+  code: string
+  message: string
+  retryable: boolean
+}
+
+export type ErrorPayload = BusinessErrorPayload | SystemErrorPayload
+
+export type ResultEnvelope<TOutput = unknown> = { ok: true; data: TOutput } | { ok: false; error: ErrorPayload }
+
+export class BusinessError extends Error {
+  readonly code: string
+  readonly data: unknown
+
+  constructor(code: string, data: unknown) {
+    super(`business error: ${code}`)
+    this.name = "BusinessError"
+    this.code = code
+    this.data = data
+  }
+
+  toPayload(): BusinessErrorPayload {
+    return { type: "business", code: this.code, data: this.data }
+  }
+}
+
+export class SystemError extends Error {
+  readonly code: string
+  readonly retryable: boolean
+
+  constructor(code: string, message: string, retryable = false) {
+    super(message)
+    this.name = "SystemError"
+    this.code = code
+    this.retryable = retryable
+  }
+
+  toPayload(): SystemErrorPayload {
+    return { type: "system", code: this.code, message: this.message, retryable: this.retryable }
+  }
+}
+
+export function isBusinessError(value: unknown): value is BusinessError {
+  return value instanceof BusinessError
+}
+
+export function isSystemError(value: unknown): value is SystemError {
+  return value instanceof SystemError
+}

package/src/sdk.executor.ts

@@ -0,0 +1,270 @@
+import { type RawOutcome, runOneShot, runStream } from "./sdk.run.ts"
+import type { FunctionContext, FunctionRegistry } from "./sdk.types.ts"
+
+export type ExecOutcome = RawOutcome | { kind: "timeout" }
+
+export interface ExecuteInput {
+  name: string
+  event: unknown
+  requestId: string
+  timeout: number
+}
+
+export interface Executor {
+  oneShot(input: ExecuteInput): Promise<ExecOutcome>
+  stream(input: ExecuteInput): AsyncGenerator<unknown, ExecOutcome, void>
+  dispose(): Promise<void>
+}
+
+export type ContextFactory = (name: string, requestId: string) => FunctionContext<Record<string, never>>
+
+function timeoutGuard(ms: number): { promise: Promise<{ kind: "timeout" }>; cancel: () => void } {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const promise = new Promise<{ kind: "timeout" }>((resolve) => {
+    timer = setTimeout(() => resolve({ kind: "timeout" }), ms)
+  })
+  return { promise, cancel: () => timer && clearTimeout(timer) }
+}
+
+export class InlineExecutor implements Executor {
+  constructor(
+    private readonly registry: FunctionRegistry,
+    private readonly makeContext: ContextFactory,
+  ) {}
+
+  async oneShot({ name, event, requestId, timeout }: ExecuteInput): Promise<ExecOutcome> {
+    const def = this.registry[name]
+    if (!def) return { kind: "crash", message: `未注册函数 ${name}` }
+    const ctx = this.makeContext(name, requestId)
+    const guard = timeoutGuard(timeout)
+    try {
+      return await Promise.race([runOneShot(def, event, ctx), guard.promise])
+    } finally {
+      guard.cancel()
+    }
+  }
+
+  async *stream({ name, event, requestId, timeout }: ExecuteInput): AsyncGenerator<unknown, ExecOutcome, void> {
+    const def = this.registry[name]
+    if (!def) return { kind: "crash", message: `未注册函数 ${name}` }
+    const ctx = this.makeContext(name, requestId)
+    const deadline = Date.now() + timeout
+    const generator = runStream(def, event, ctx)
+    while (true) {
+      const next = await generator.next()
+      if (next.done) return next.value
+      if (Date.now() > deadline) return { kind: "timeout" }
+      yield next.value
+    }
+  }
+
+  async dispose(): Promise<void> {}
+}
+
+interface PendingOneShot {
+  kind: "oneShot"
+  resolve: (outcome: RawOutcome) => void
+}
+
+interface PendingStream {
+  kind: "stream"
+  push: (chunk: unknown) => void
+  end: (outcome: RawOutcome) => void
+}
+
+type WorkerMessage =
+  | { t: "ready" }
+  | { t: "result"; id: number; outcome: RawOutcome }
+  | { t: "chunk"; id: number; data: unknown }
+  | { t: "end"; id: number; outcome: RawOutcome }
+
+class WorkerHandle {
+  private readonly proc: Bun.Subprocess
+  private readonly pending = new Map<number, PendingOneShot | PendingStream>()
+  private seq = 0
+  private markReady!: () => void
+  readonly ready: Promise<void>
+
+  constructor(args: string[], env: Record<string, string>) {
+    this.ready = new Promise((resolve) => {
+      this.markReady = resolve
+    })
+    this.proc = Bun.spawn(args, {
+      env,
+      stdio: ["ignore", "inherit", "inherit"],
+      serialization: "json",
+      ipc: (message) => this.onMessage(message as WorkerMessage),
+    })
+  }
+
+  private onMessage(message: WorkerMessage): void {
+    if (message.t === "ready") {
+      this.markReady()
+      return
+    }
+    const entry = this.pending.get(message.id)
+    if (!entry) return
+    if (message.t === "result" && entry.kind === "oneShot") {
+      this.pending.delete(message.id)
+      entry.resolve(message.outcome)
+    } else if (message.t === "chunk" && entry.kind === "stream") {
+      entry.push(message.data)
+    } else if (message.t === "end" && entry.kind === "stream") {
+      this.pending.delete(message.id)
+      entry.end(message.outcome)
+    }
+  }
+
+  oneShot(name: string, event: unknown, requestId: string): Promise<RawOutcome> {
+    const id = ++this.seq
+    return new Promise<RawOutcome>((resolve) => {
+      this.pending.set(id, { kind: "oneShot", resolve })
+      this.proc.send({ t: "call", id, stream: false, name, event, requestId })
+    })
+  }
+
+  stream(name: string, event: unknown, requestId: string): AsyncGenerator<unknown, RawOutcome, void> {
+    const id = ++this.seq
+    const queue: unknown[] = []
+    let terminal: RawOutcome | undefined
+    let notify: (() => void) | undefined
+
+    const wake = () => {
+      const fn = notify
+      notify = undefined
+      fn?.()
+    }
+    this.pending.set(id, {
+      kind: "stream",
+      push: (chunk) => {
+        queue.push(chunk)
+        wake()
+      },
+      end: (outcome) => {
+        terminal = outcome
+        wake()
+      },
+    })
+    this.proc.send({ t: "call", id, stream: true, name, event, requestId })
+
+    async function* drain(): AsyncGenerator<unknown, RawOutcome, void> {
+      while (true) {
+        if (queue.length > 0) {
+          yield queue.shift()
+          continue
+        }
+        if (terminal) return terminal
+        await new Promise<void>((resolve) => {
+          notify = resolve
+        })
+      }
+    }
+    return drain()
+  }
+
+  kill(): void {
+    this.proc.kill()
+  }
+}
+
+export interface ProcessExecutorOptions {
+  args: string[]
+  env: Record<string, string>
+  pooled: boolean
+  size: number
+}
+
+export class ProcessExecutor implements Executor {
+  private readonly idle: WorkerHandle[] = []
+  private readonly waiters: Array<(worker: WorkerHandle) => void> = []
+  private created = 0
+
+  constructor(private readonly options: ProcessExecutorOptions) {}
+
+  private spawn(): WorkerHandle {
+    return new WorkerHandle(this.options.args, { ...this.options.env, ATOMFN_WORKER: "1" })
+  }
+
+  private async acquire(): Promise<WorkerHandle> {
+    if (!this.options.pooled) {
+      const worker = this.spawn()
+      await worker.ready
+      return worker
+    }
+    const existing = this.idle.pop()
+    if (existing) return existing
+    if (this.created < this.options.size) {
+      this.created += 1
+      const worker = this.spawn()
+      await worker.ready
+      return worker
+    }
+    return new Promise<WorkerHandle>((resolve) => this.waiters.push(resolve))
+  }
+
+  private release(worker: WorkerHandle): void {
+    if (!this.options.pooled) {
+      worker.kill()
+      return
+    }
+    const waiter = this.waiters.shift()
+    if (waiter) waiter(worker)
+    else this.idle.push(worker)
+  }
+
+  private discard(worker: WorkerHandle): void {
+    worker.kill()
+    if (!this.options.pooled) return
+    this.created -= 1
+    const waiter = this.waiters.shift()
+    if (waiter) {
+      this.created += 1
+      const replacement = this.spawn()
+      replacement.ready.then(() => waiter(replacement))
+    }
+  }
+
+  async oneShot({ name, event, requestId, timeout }: ExecuteInput): Promise<ExecOutcome> {
+    const worker = await this.acquire()
+    const guard = timeoutGuard(timeout)
+    try {
+      const outcome = await Promise.race([worker.oneShot(name, event, requestId), guard.promise])
+      if (outcome.kind === "timeout") {
+        this.discard(worker)
+        return outcome
+      }
+      this.release(worker)
+      return outcome
+    } finally {
+      guard.cancel()
+    }
+  }
+
+  async *stream({ name, event, requestId, timeout }: ExecuteInput): AsyncGenerator<unknown, ExecOutcome, void> {
+    const worker = await this.acquire()
+    const deadline = Date.now() + timeout
+    const generator = worker.stream(name, event, requestId)
+    try {
+      while (true) {
+        const next = await generator.next()
+        if (next.done) {
+          this.release(worker)
+          return next.value
+        }
+        if (Date.now() > deadline) {
+          this.discard(worker)
+          return { kind: "timeout" }
+        }
+        yield next.value
+      }
+    } catch (error) {
+      this.discard(worker)
+      return { kind: "crash", message: error instanceof Error ? error.message : String(error) }
+    }
+  }
+
+  async dispose(): Promise<void> {
+    for (const worker of this.idle) worker.kill()
+    this.idle.length = 0
+  }
+}

package/src/sdk.invoke.ts

@@ -0,0 +1,140 @@
+import { SYSTEM_ERROR } from "./sdk.consts.ts"
+import type { ResultEnvelope, SystemErrorPayload } from "./sdk.errors.ts"
+import type { ExecOutcome, Executor } from "./sdk.executor.ts"
+import type {
+  AnyFunctionDefinition,
+  AsyncFunctionDefinition,
+  AsyncStreamFunctionDefinition,
+  FunctionDefinition,
+  StreamFunctionDefinition,
+} from "./sdk.types.ts"
+import { validate } from "./sdk.validate.ts"
+
+export interface InvokeDeps {
+  executor: Executor
+  name: string
+  requestId: string
+  defaultTimeout: number
+}
+
+export interface OneShotResult {
+  status: number
+  envelope: ResultEnvelope
+}
+
+function systemError(code: string, message: string, retryable = false): SystemErrorPayload {
+  return { type: "system", code, message, retryable }
+}
+
+function mapTerminal(def: AnyFunctionDefinition, outcome: ExecOutcome): OneShotResult {
+  if (outcome.kind === "timeout") {
+    return { status: 504, envelope: { ok: false, error: systemError(SYSTEM_ERROR.FUNCTION_TIMEOUT, "执行超时") } }
+  }
+  if (outcome.kind === "business") {
+    return {
+      status: 200,
+      envelope: { ok: false, error: { type: "business", code: outcome.code, data: outcome.data } },
+    }
+  }
+  if (outcome.kind === "crash") {
+    return { status: 500, envelope: { ok: false, error: systemError(SYSTEM_ERROR.FUNCTION_ERROR, outcome.message) } }
+  }
+  const checked = validate(def.output, outcome.data)
+  if (!checked.ok) {
+    return {
+      status: 500,
+      envelope: { ok: false, error: systemError(SYSTEM_ERROR.OUTPUT_INVALID, checked.issues.join("; ")) },
+    }
+  }
+  return { status: 200, envelope: { ok: true, data: checked.value } }
+}
+
+export async function invokeOneShot(
+  def: FunctionDefinition | AsyncFunctionDefinition,
+  body: unknown,
+  deps: InvokeDeps,
+): Promise<OneShotResult> {
+  const parsed = validate(def.input, body)
+  if (!parsed.ok) {
+    return {
+      status: 422,
+      envelope: { ok: false, error: systemError(SYSTEM_ERROR.VALIDATION_FAILED, parsed.issues.join("; ")) },
+    }
+  }
+
+  const timeout = def.config.timeout ?? deps.defaultTimeout
+  const outcome = await deps.executor.oneShot({
+    name: deps.name,
+    event: parsed.value,
+    requestId: deps.requestId,
+    timeout,
+  })
+  return mapTerminal(def, outcome)
+}
+
+const SSE_HEADERS = { "content-type": "text/event-stream", "cache-control": "no-cache", connection: "keep-alive" }
+
+function sseEvent(event: string, data: unknown): string {
+  return `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`
+}
+
+export function invokeStream(
+  def: StreamFunctionDefinition | AsyncStreamFunctionDefinition,
+  body: unknown,
+  deps: InvokeDeps,
+): Response {
+  const parsed = validate(def.input, body)
+  if (!parsed.ok) {
+    const envelope: ResultEnvelope = {
+      ok: false,
+      error: systemError(SYSTEM_ERROR.VALIDATION_FAILED, parsed.issues.join("; ")),
+    }
+    return Response.json(envelope, { status: 422 })
+  }
+
+  const timeout = def.config.timeout ?? deps.defaultTimeout
+  const encoder = new TextEncoder()
+
+  const stream = new ReadableStream<Uint8Array>({
+    async start(controller) {
+      const generator = deps.executor.stream({
+        name: deps.name,
+        event: parsed.value,
+        requestId: deps.requestId,
+        timeout,
+      })
+      while (true) {
+        const next = await generator.next()
+        if (next.done) {
+          const outcome = next.value
+          if (outcome.kind === "ok") {
+            controller.enqueue(encoder.encode(sseEvent("done", {})))
+          } else if (outcome.kind === "business") {
+            controller.enqueue(
+              encoder.encode(sseEvent("error", { type: "business", code: outcome.code, data: outcome.data })),
+            )
+          } else if (outcome.kind === "timeout") {
+            controller.enqueue(
+              encoder.encode(sseEvent("error", systemError(SYSTEM_ERROR.FUNCTION_TIMEOUT, "执行超时"))),
+            )
+          } else {
+            controller.enqueue(
+              encoder.encode(sseEvent("error", systemError(SYSTEM_ERROR.FUNCTION_ERROR, outcome.message))),
+            )
+          }
+          break
+        }
+        controller.enqueue(encoder.encode(sseEvent("chunk", next.value)))
+      }
+      controller.close()
+    },
+  })
+
+  return new Response(stream, { headers: SSE_HEADERS })
+}
+
+export function isStreamKind(
+  def: AnyFunctionDefinition,
+): def is StreamFunctionDefinition | AsyncStreamFunctionDefinition {
+  return def.kind === "streamFunction" || def.kind === "asyncStreamFunction"
+}

package/src/sdk.log.ts

@@ -0,0 +1,44 @@
+import type { LogFields, Logger } from "./sdk.types.ts"
+
+export type LogLevel = "debug" | "info" | "warn" | "error"
+
+export interface LogRecord {
+  ts: string
+  level: LogLevel
+  project: string
+  bundle: string
+  function: string
+  requestId: string
+  msg: string
+  fields?: LogFields
+}
+
+export interface LogSink {
+  write(record: LogRecord): void
+}
+
+export interface LogContext {
+  project: string
+  bundle: string
+  function: string
+  requestId: string
+}
+
+export const stdoutSink: LogSink = {
+  write(record) {
+    const { fields, ...rest } = record
+    process.stdout.write(`${JSON.stringify({ ...rest, ...fields })}\n`)
+  },
+}
+
+export function createLogger(ctx: LogContext, sink: LogSink): Logger {
+  const emit = (level: LogLevel, msg: string, fields?: LogFields) => {
+    sink.write({ ts: new Date().toISOString(), level, ...ctx, msg, fields })
+  }
+  return {
+    debug: (msg, fields) => emit("debug", msg, fields),
+    info: (msg, fields) => emit("info", msg, fields),
+    warn: (msg, fields) => emit("warn", msg, fields),
+    error: (msg, fields) => emit("error", msg, fields),
+  }
+}

package/src/sdk.run.ts

@@ -0,0 +1,43 @@
+import { BusinessError } from "./sdk.errors.ts"
+import type { AnyFunctionDefinition, FunctionContext } from "./sdk.types.ts"
+
+export type RawOutcome =
+  | { kind: "ok"; data: unknown }
+  | { kind: "business"; code: string; data: unknown }
+  | { kind: "crash"; message: string }
+
+function crashMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+function fromError(error: unknown): RawOutcome {
+  if (error instanceof BusinessError) return { kind: "business", code: error.code, data: error.data }
+  return { kind: "crash", message: crashMessage(error) }
+}
+
+export async function runOneShot(
+  def: AnyFunctionDefinition,
+  event: unknown,
+  ctx: FunctionContext<Record<string, never>>,
+): Promise<RawOutcome> {
+  try {
+    const data = await (def.handler as (e: unknown, c: unknown) => unknown)(event, ctx)
+    return { kind: "ok", data }
+  } catch (error) {
+    return fromError(error)
+  }
+}
+
+export async function* runStream(
+  def: AnyFunctionDefinition,
+  event: unknown,
+  ctx: FunctionContext<Record<string, never>>,
+): AsyncGenerator<unknown, RawOutcome, void> {
+  try {
+    const iterator = (def.handler as (e: unknown, c: unknown) => AsyncIterable<unknown>)(event, ctx)
+    for await (const partial of iterator) yield partial
+    return { kind: "ok", data: undefined }
+  } catch (error) {
+    return fromError(error)
+  }
+}

package/src/sdk.runtime.ts

@@ -0,0 +1,177 @@
+import { DEFAULT_BUNDLE_PORT, HEALTH_PATH, INVOKE_PATH_PREFIX, REQUEST_ID_HEADER, SYSTEM_ERROR } from "./sdk.consts.ts"
+import { startConsumer } from "./sdk.consumer.ts"
+import { createContext } from "./sdk.context.ts"
+import { type ContextFactory, type Executor, InlineExecutor, ProcessExecutor } from "./sdk.executor.ts"
+import { invokeOneShot, invokeStream, isStreamKind } from "./sdk.invoke.ts"
+import { type LogSink, stdoutSink } from "./sdk.log.ts"
+import type { AnyFunctionDefinition, ExecutionMode, FunctionRegistry } from "./sdk.types.ts"
+import { runWorker } from "./sdk.worker.ts"
+
+export interface ServeOptions {
+  port: number
+  project: string
+  bundle: string
+  sink: LogSink
+  defaultTimeout: number
+  poolSize: number
+  memoryLimitMb?: number
+}
+
+const DEFAULT_TIMEOUT = 30_000
+const MEMORY_BACKPRESSURE_RATIO = 0.9
+
+function resolveOptions(overrides?: Partial<ServeOptions>): ServeOptions {
+  const env = process.env
+  const memory = env.ATOMFN_MEMORY_MB ? Number(env.ATOMFN_MEMORY_MB) : undefined
+  return {
+    port: overrides?.port ?? (env.ATOMFN_PORT ? Number(env.ATOMFN_PORT) : DEFAULT_BUNDLE_PORT),
+    project: overrides?.project ?? env.ATOMFN_PROJECT ?? "default",
+    bundle: overrides?.bundle ?? env.ATOMFN_BUNDLE ?? "default",
+    sink: overrides?.sink ?? stdoutSink,
+    defaultTimeout: overrides?.defaultTimeout ?? DEFAULT_TIMEOUT,
+    poolSize: overrides?.poolSize ?? Math.max(1, navigator.hardwareConcurrency || 1),
+    memoryLimitMb: overrides?.memoryLimitMb ?? (memory && Number.isFinite(memory) ? memory : undefined),
+  }
+}
+
+function requestId(request: Request): string {
+  return request.headers.get(REQUEST_ID_HEADER) ?? crypto.randomUUID()
+}
+
+function makeContextFactory(options: ServeOptions): ContextFactory {
+  return (name, id) =>
+    createContext<Record<string, never>>({
+      project: options.project,
+      bundle: options.bundle,
+      function: name,
+      requestId: id,
+      sink: options.sink,
+    })
+}
+
+interface ExecutorRouter {
+  pick: (def: AnyFunctionDefinition) => Executor
+  dispose: () => Promise<void>
+}
+
+function buildExecutorRouter(registry: FunctionRegistry, options: ServeOptions): ExecutorRouter {
+  const inline = new InlineExecutor(registry, makeContextFactory(options))
+  const workerEnv: Record<string, string> = {
+    ...(process.env as Record<string, string>),
+    ATOMFN_PROJECT: options.project,
+    ATOMFN_BUNDLE: options.bundle,
+  }
+  let pooled: ProcessExecutor | undefined
+  let isolated: ProcessExecutor | undefined
+
+  function pick(def: AnyFunctionDefinition): Executor {
+    const mode: ExecutionMode = def.config.execution ?? "inline"
+    if (mode === "inline") return inline
+    if (mode === "pooled") {
+      pooled ??= new ProcessExecutor({ args: [...process.argv], env: workerEnv, pooled: true, size: options.poolSize })
+      return pooled
+    }
+    isolated ??= new ProcessExecutor({ args: [...process.argv], env: workerEnv, pooled: false, size: 0 })
+    return isolated
+  }
+
+  async function dispose(): Promise<void> {
+    await inline.dispose()
+    await pooled?.dispose()
+    await isolated?.dispose()
+  }
+
+  return { pick, dispose }
+}
+
+function overloaded(options: ServeOptions): boolean {
+  if (!options.memoryLimitMb) return false
+  const rssMb = process.memoryUsage().rss / (1024 * 1024)
+  return rssMb > options.memoryLimitMb * MEMORY_BACKPRESSURE_RATIO
+}
+
+export function serve(
+  registry: FunctionRegistry,
+  overrides?: Partial<ServeOptions>,
+): Bun.Server<undefined> | undefined {
+  const options = resolveOptions(overrides)
+
+  if (process.env.ATOMFN_WORKER === "1") {
+    runWorker(registry, makeContextFactory(options))
+    return undefined
+  }
+
+  const router = buildExecutorRouter(registry, options)
+
+  const databaseUrl = process.env.ATOMFN_DATABASE_URL?.trim()
+  if (databaseUrl) {
+    startConsumer({
+      databaseUrl,
+      project: options.project,
+      bundle: options.bundle,
+      registry,
+      makeContext: makeContextFactory(options),
+    })
+  }
+
+  return Bun.serve({
+    port: options.port,
+    async fetch(request) {
+      const url = new URL(request.url)
+
+      if (request.method === "GET" && url.pathname === HEALTH_PATH) {
+        const functions = Object.entries(registry).map(([name, def]) => ({ name, kind: def.kind }))
+        return Response.json({ ok: true, functions })
+      }
+
+      if (request.method === "POST" && url.pathname.startsWith(INVOKE_PATH_PREFIX)) {
+        const name = url.pathname.slice(INVOKE_PATH_PREFIX.length)
+        const def = registry[name]
+        if (!def) {
+          return Response.json(
+            {
+              ok: false,
+              error: { type: "system", code: SYSTEM_ERROR.NOT_FOUND, message: `未找到函数 ${name}`, retryable: false },
+            },
+            { status: 404 },
+          )
+        }
+
+        const error = {
+          type: "system" as const,
+          code: "OVERLOADED",
+          message: "内存接近上限，请稍后重试",
+          retryable: true,
+        }
+        if (overloaded(options)) {
+          return Response.json({ ok: false, error }, { status: 503, headers: { "retry-after": "1" } })
+        }
+
+        const id = requestId(request)
+        const body = await readBody(request)
+        const deps = { executor: router.pick(def), name, requestId: id, defaultTimeout: options.defaultTimeout }
+
+        if (isStreamKind(def)) {
+          const response = invokeStream(def, body, deps)
+          response.headers.set(REQUEST_ID_HEADER, id)
+          return response
+        }
+
+        const { status, envelope } = await invokeOneShot(def, body, deps)
+        return Response.json(envelope, { status, headers: { [REQUEST_ID_HEADER]: id } })
+      }
+
+      return new Response("Not Found", { status: 404 })
+    },
+  })
+}
+
+async function readBody(request: Request): Promise<unknown> {
+  const text = await request.text()
+  if (!text) return undefined
+  try {
+    return JSON.parse(text)
+  } catch {
+    return text
+  }
+}

package/src/sdk.types.ts

@@ -0,0 +1,94 @@
+import type { Static, TSchema } from "typebox"
+import type { BusinessError } from "./sdk.errors.ts"
+
+export type ExecutionMode = "inline" | "pooled" | "isolated"
+
+export type ErrorsSchema = Record<string, TSchema>
+
+export type DeepPartial<T> = T extends (infer U)[]
+  ? DeepPartial<U>[]
+  : T extends object
+    ? { [K in keyof T]?: DeepPartial<T[K]> }
+    : T
+
+export interface LogFields {
+  [key: string]: unknown
+}
+
+export interface Logger {
+  debug(message: string, fields?: LogFields): void
+  info(message: string, fields?: LogFields): void
+  warn(message: string, fields?: LogFields): void
+  error(message: string, fields?: LogFields): void
+}
+
+export interface FunctionContext<TErrors extends ErrorsSchema> {
+  readonly requestId: string
+  readonly log: Logger
+  error<TCode extends keyof TErrors & string>(code: TCode, data: Static<TErrors[TCode]>): BusinessError
+}
+
+export interface FunctionConfig {
+  execution?: ExecutionMode
+  timeout?: number
+  maxConcurrency?: number
+}
+
+export type FunctionKind = "function" | "streamFunction" | "asyncFunction" | "asyncStreamFunction"
+
+interface BaseDefinition<TInput extends TSchema, TOutput extends TSchema, TErrors extends ErrorsSchema> {
+  readonly input: TInput
+  readonly output: TOutput
+  readonly errors: TErrors
+  readonly config: FunctionConfig
+}
+
+export interface FunctionDefinition<
+  TInput extends TSchema = TSchema,
+  TOutput extends TSchema = TSchema,
+  TErrors extends ErrorsSchema = ErrorsSchema,
+> extends BaseDefinition<TInput, TOutput, TErrors> {
+  readonly kind: "function"
+  readonly handler: (event: Static<TInput>, ctx: FunctionContext<TErrors>) => Bun.MaybePromise<Static<TOutput>>
+}
+
+export interface StreamFunctionDefinition<
+  TInput extends TSchema = TSchema,
+  TOutput extends TSchema = TSchema,
+  TErrors extends ErrorsSchema = ErrorsSchema,
+> extends BaseDefinition<TInput, TOutput, TErrors> {
+  readonly kind: "streamFunction"
+  readonly handler: (
+    event: Static<TInput>,
+    ctx: FunctionContext<TErrors>,
+  ) => AsyncGenerator<DeepPartial<Static<TOutput>>, void, void>
+}
+
+export interface AsyncFunctionDefinition<
+  TInput extends TSchema = TSchema,
+  TOutput extends TSchema = TSchema,
+  TErrors extends ErrorsSchema = ErrorsSchema,
+> extends BaseDefinition<TInput, TOutput, TErrors> {
+  readonly kind: "asyncFunction"
+  readonly handler: (event: Static<TInput>, ctx: FunctionContext<TErrors>) => Bun.MaybePromise<Static<TOutput>>
+}
+
+export interface AsyncStreamFunctionDefinition<
+  TInput extends TSchema = TSchema,
+  TOutput extends TSchema = TSchema,
+  TErrors extends ErrorsSchema = ErrorsSchema,
+> extends BaseDefinition<TInput, TOutput, TErrors> {
+  readonly kind: "asyncStreamFunction"
+  readonly handler: (
+    event: Static<TInput>,
+    ctx: FunctionContext<TErrors>,
+  ) => AsyncGenerator<DeepPartial<Static<TOutput>>, void, void>
+}
+
+export type AnyFunctionDefinition =
+  | FunctionDefinition
+  | StreamFunctionDefinition
+  | AsyncFunctionDefinition
+  | AsyncStreamFunctionDefinition
+
+export type FunctionRegistry = Record<string, AnyFunctionDefinition>

package/src/sdk.validate.ts

@@ -0,0 +1,11 @@
+import type { TSchema } from "typebox"
+import { Value } from "typebox/value"
+
+export type ValidationResult = { ok: true; value: unknown } | { ok: false; issues: string[] }
+
+export function validate(schema: TSchema, value: unknown): ValidationResult {
+  const filled = Value.Default(schema, Value.Clone(value))
+  if (Value.Check(schema, filled)) return { ok: true, value: filled }
+  const issues = [...Value.Errors(schema, filled)].map((e) => `${e.instancePath || "/"}: ${e.message}`)
+  return { ok: false, issues }
+}

package/src/sdk.worker.ts

@@ -0,0 +1,43 @@
+import type { ContextFactory } from "./sdk.executor.ts"
+import { runOneShot, runStream } from "./sdk.run.ts"
+import type { FunctionRegistry } from "./sdk.types.ts"
+
+interface CallMessage {
+  t: "call"
+  id: number
+  stream: boolean
+  name: string
+  event: unknown
+  requestId: string
+}
+
+export function runWorker(registry: FunctionRegistry, makeContext: ContextFactory): void {
+  process.on("message", async (raw: unknown) => {
+    const message = raw as CallMessage
+    if (message.t !== "call") return
+
+    const def = registry[message.name]
+    if (!def) {
+      process.send?.({ t: "result", id: message.id, outcome: { kind: "crash", message: `未注册函数 ${message.name}` } })
+      return
+    }
+
+    const ctx = makeContext(message.name, message.requestId)
+    if (message.stream) {
+      const generator = runStream(def, message.event, ctx)
+      while (true) {
+        const next = await generator.next()
+        if (next.done) {
+          process.send?.({ t: "end", id: message.id, outcome: next.value })
+          break
+        }
+        process.send?.({ t: "chunk", id: message.id, data: next.value })
+      }
+    } else {
+      const outcome = await runOneShot(def, message.event, ctx)
+      process.send?.({ t: "result", id: message.id, outcome })
+    }
+  })
+
+  process.send?.({ t: "ready" })
+}