@agfpd/iapeer 0.2.9 → 0.2.11

package/src/storage/rotatelog.test.ts

@@ -0,0 +1,44 @@
+// rotatelog — the generic rotated-logfmt-append primitive (promoted from
+// lifecycle/eventlog.ts when the daemon's delivery.log became the second
+// producer). The logfmt formatting (fmtValue/formatEventLine) is pinned in
+// lifecycle/eventlog.test.ts (its historical home, re-exported); these tests
+// cover what is NEW at this layer: the path-parameterized append + rotation.
+
+import { afterEach, describe, expect, test } from 'bun:test'
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { appendRotatedEvent } from './rotatelog.ts'
+
+const dirs: string[] = []
+function mkTmp(): string {
+  const d = mkdtempSync(join(tmpdir(), 'iapeer-rotatelog-'))
+  dirs.push(d)
+  return d
+}
+afterEach(() => {
+  while (dirs.length) rmSync(dirs.pop()!, { recursive: true, force: true })
+})
+
+describe('appendRotatedEvent', () => {
+  test('creates the parent dir and appends one ts-stamped logfmt line', () => {
+    const path = join(mkTmp(), 'deep', 'nested', 'some.log')
+    appendRotatedEvent(path, { ev: 'delivery', ok: 'true', note: 'two words' }, { nowMs: 1750000000000 })
+    const text = readFileSync(path, 'utf8')
+    expect(text).toBe('ts=2025-06-15T15:06:40.000Z ev=delivery ok=true note="two words"\n')
+  })
+
+  test('rotates base → .1 at maxBytes and drops beyond keep', () => {
+    const path = join(mkTmp(), 'r.log')
+    const line = { ev: 'x', pad: 'a'.repeat(50) } // ~65 bytes/line
+    // maxBytes 100 → every second append rotates; keep 1 → no .2 ever exists.
+    for (let i = 0; i < 6; i++) appendRotatedEvent(path, line, { maxBytes: 100, keep: 1 })
+    expect(existsSync(path)).toBe(true)
+    expect(existsSync(`${path}.1`)).toBe(true)
+    expect(existsSync(`${path}.2`)).toBe(false)
+  })
+
+  test('never throws on an unwritable path (best-effort observability)', () => {
+    expect(() => appendRotatedEvent('/dev/null/impossible/x.log', { ev: 'x' })).not.toThrow()
+  })
+})

package/src/storage/rotatelog.ts

@@ -0,0 +1,109 @@
+// Rotated logfmt append — the GENERIC durable-log primitive, promoted out of
+// lifecycle/eventlog.ts (its header anticipated exactly this: "the rotate-append
+// primitive is path-parameterized, so the adjacent 'log rotation' phase can
+// promote it to storage/ and point other log producers at it"). Producers today:
+//   • lifecycle.log  (lifecycle/eventlog.ts — daemon lifecycle decisions)
+//   • delivery.log   (daemon/deliverylog.ts — per-delivery outcomes, Ф-#8a)
+//
+// Design (carried verbatim from eventlog):
+//   • One line per event, logfmt (`key=value`, values quoted iff they contain
+//     whitespace/quotes/`=`). Human-greppable AND machine-parseable.
+//   • Append-only, app-managed SIZE rotation (base → .1 … .keep). This is the
+//     "встроенная ротация" class (Фаза — Ротация логов iapeer): a log OUR code
+//     writes rotates itself in the writer; external rotation is only for logs
+//     written by processes we don't control.
+//   • The target PATH is passed IN by the caller (who routes it through cfg),
+//     never re-resolved from env here — so a sandboxed caller cfg sandboxes the
+//     log too (no leak to the real ~/.iapeer).
+//   • Best-effort throughout: a write/rotate failure is swallowed. Observability
+//     must never take down the daemon or fail a wake/reap/delivery.
+
+import { appendFileSync, mkdirSync, renameSync, rmSync, statSync } from 'fs'
+import { dirname } from 'path'
+
+/** Default cap per log file before it rotates to <path>.1. */
+export const DEFAULT_LOG_MAX_BYTES = 5 * 1024 * 1024 // 5 MiB
+/** Default number of rotated backups kept (<path>.1 … .KEEP). */
+export const DEFAULT_LOG_KEEP = 5
+
+/** logfmt value: bare token, or double-quoted with `"`/`\` escaped, when it
+ *  contains whitespace, `=` or `"`. Empty string → `""`. */
+export function fmtValue(v: string | number): string {
+  const s = String(v)
+  if (s === '') return '""'
+  if (/[\s"=]/.test(s)) return `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`
+  return s
+}
+
+/** Render one logfmt line (ts first, then fields in insertion order; undefined
+ *  fields are skipped). No trailing newline. Pure — unit-testable. */
+export function formatEventLine(nowMs: number, fields: Record<string, string | number | undefined>): string {
+  const parts = [`ts=${new Date(nowMs).toISOString()}`]
+  for (const [k, v] of Object.entries(fields)) {
+    if (v === undefined) continue
+    parts.push(`${k}=${fmtValue(v)}`)
+  }
+  return parts.join(' ')
+}
+
+/** Size-rotate `path` (and its .1 … .keep backups) when the next line would push
+ *  it over `maxBytes`. Drops the oldest, shifts each backup up by one, base→.1.
+ *  Best-effort: any fs hiccup leaves the chain as-is (we then just append). */
+function rotateIfNeeded(path: string, lineLen: number, maxBytes: number, keep: number): void {
+  let size: number
+  try {
+    size = statSync(path).size
+  } catch {
+    return // no file yet → nothing to rotate
+  }
+  if (size + lineLen <= maxBytes) return
+  try {
+    rmSync(`${path}.${keep}`, { force: true })
+  } catch {
+    /* best-effort */
+  }
+  for (let i = keep - 1; i >= 1; i--) {
+    try {
+      renameSync(`${path}.${i}`, `${path}.${i + 1}`)
+    } catch {
+      /* that backup may not exist yet */
+    }
+  }
+  try {
+    renameSync(path, `${path}.1`)
+  } catch {
+    /* best-effort */
+  }
+}
+
+export interface AppendRotatedOptions {
+  /** Stamp the line with this epoch-ms (a caller may pass its own tick clock so the
+   *  log timestamp agrees with its accounting). Default Date.now(). */
+  nowMs?: number
+  /** Rotation cap per file (default DEFAULT_LOG_MAX_BYTES). */
+  maxBytes?: number
+  /** Rotated backups kept (default DEFAULT_LOG_KEEP). */
+  keep?: number
+}
+
+/**
+ * Append one logfmt event line to the rotated log at `path` (full file path,
+ * routed through the caller's cfg). Creates the parent dir (0700) and the file
+ * (0600) as needed. Fully best-effort — never throws.
+ */
+export function appendRotatedEvent(
+  path: string,
+  fields: Record<string, string | number | undefined>,
+  opts: AppendRotatedOptions = {},
+): void {
+  const line = `${formatEventLine(opts.nowMs ?? Date.now(), fields)}\n`
+  const maxBytes = opts.maxBytes ?? DEFAULT_LOG_MAX_BYTES
+  const keep = opts.keep ?? DEFAULT_LOG_KEEP
+  try {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 })
+    rotateIfNeeded(path, line.length, maxBytes, keep)
+    appendFileSync(path, line, { mode: 0o600 })
+  } catch {
+    /* observability is best-effort — a log failure must never break the caller */
+  }
+}

package/src/transport/index.ts

@@ -378,6 +378,14 @@ export interface RouteResult {
   delivered_to: { personality: string; runtime: string }
   woke: boolean
   ts: string
+  /** wake_policy:"ephemeral" M3 — true when the message was ENQUEUED for a
+   *  stateless worker rather than injected/woken synchronously: the daemon
+   *  drains the per-peer FIFO one task per fresh session (async). The
+   *  substantive result arrives as the worker's own reply (FaaS semantics);
+   *  `delivered_to` names the ACCEPTING queue identity, not a live session. */
+  queued?: boolean
+  /** Queue depth right after the enqueue (observability; only with queued). */
+  queueDepth?: number
 }
 
 // WakeFn — the lifecycle wake primitive, INJECTED (transport never imports
@@ -403,9 +411,29 @@ export interface WakeOutcome {
 }
 export type WakeFn = (req: WakeRequest) => Promise<WakeOutcome>
 
+/** wake_policy:"ephemeral" M3 — the injected serial-queue delivery seam. Like
+ *  WakeFn, transport never imports lifecycle: the daemon composition (main.ts)
+ *  wires the queue + drain behind this contract; absent → every target takes
+ *  the normal live/miss path (library/CLI/test callers unchanged). */
+export interface EphemeralRouteDeps {
+  /** Is the target peer (by its registry cwd) an ephemeral stateless worker? */
+  isEphemeral: (cwd: string) => boolean
+  /** Always-enqueue delivery: enqueue + async drain kick → fast `{queued:true}`
+   *  ack. MUST NOT block on the wake (the sender's content-level answer is the
+   *  worker's own reply, not this transport ack). */
+  deliver: (args: {
+    peer: PeerRecord
+    envelope: string
+    topic?: string
+    runtime?: string
+  }) => Promise<Result<RouteResult>>
+}
+
 export interface RouteDeps {
   /** On a miss, wake the dead peer instead of returning offline (Ф2). */
   wake?: WakeFn
+  /** Ephemeral-target serial-queue delivery (M3); absent → normal routing. */
+  ephemeral?: EphemeralRouteDeps
 }
 
 function truncateTopic(raw: string | undefined): string | undefined {
@@ -483,6 +511,17 @@ export async function routeSend(
     message,
   })
 
+  // M3 wake_policy:"ephemeral" — an ephemeral target is NEVER injected into a live
+  // session and never woken synchronously here: the delivery is ALWAYS enqueued
+  // (per-peer disk FIFO) and drained one task per fresh session, asynchronously.
+  // ONE delivery path by design: no live/miss race, strict FIFO, a clean context
+  // window per task. Self-send is refused up front (a worker enqueueing to itself
+  // would deadlock its own die-after-reply reap on a forever-non-empty queue).
+  if (deps.ephemeral?.isEphemeral(peer.cwd)) {
+    if (caller.personality === peer.personality) return err('cannot send to self')
+    return deps.ephemeral.deliver({ peer, envelope, topic, runtime })
+  }
+
   const target = resolvePeerDeliveryTarget(personality, runtime, peer)
   if (target.ok) {
     if (target.value.address === caller.address) return err('cannot send to self')