@blamejs/core 0.6.32 → 0.6.33

package/CHANGELOG.md

@@ -8,6 +8,7 @@ upgrading across more than a few patches at a time.
 
 ## v0.6.x
 
+- **0.6.33** (2026-05-02) — log-stream sinks parity sweep. **`b.logStream` syslog sink (RFC 5424)** — first-class `protocol: "syslog"` for `b.logStream.init({ sinks: { ... } })`; new module `lib/log-stream-syslog.js`. URL-driven transport selection: `udp://host:514` / `tcp://host:514` / `tls://host:6514`. UDP is best-effort one-datagram-per-record; TCP / TLS use RFC 6587 octet-counting framing (`<length> <message>`) so collectors that prefer it over the older non-transparent newline framing parse cleanly. TLS is TLS 1.3 minimum; operators with private CAs pass `ca` (PEM string or array) for trust pinning, `servername` for SNI override (auto-suppressed on IP literals per the v0.6.28 redis-client convention). Outgoing records are formatted with PRI = `(facility << 3) | severity`, default facility `local0` (16), severity mapped from the framework's level field (debug=7 / info=6 / warn=4 / error=3); operators override via `facility`, `appName` (default `blamejs`), `procId` (default `process.pid`), `hostname` (default `os.hostname()`), `structuredData` (default `-`). Meta is JSON-encoded into the MSG body so the structured payload survives the wire as a single token. TCP / TLS reconnect with exponential backoff (default 250ms→30s); records buffer during the down window with `bufferLimit`-bounded oldest-drop semantics, replay on reconnect. `close()` waits up to 3s for an in-flight (re)connect to drain the buffer before tearing down — without this the slower TLS handshake raced fire-and-forget shutdown emits and silently dropped records. Operator-supplied `onDrop({reason, batch, error})` surfaces every drop class (`overflow` / `udp-send-error` / `write-error` / `sink-closed`). Removed `syslog` from `DEFERRED_PROTOCOLS`. **`b.logStream` cloudwatch sink: `autoCreate`** — pass `{ autoCreate: true }` to have the framework issue `CreateLogGroup` + `CreateLogStream` on first emit so operators provisioning collectors via env vars / runbooks don't need a separate aws-cli step. Idempotent: AWS's `ResourceAlreadyExistsException` is treated as success on both calls. Hard failures (5xx, AccessDenied, etc.) drop the batch with `onDrop` reason `autocreate-failed`. Default remains `autoCreate: false` so the AWS posture (operator pre-creates via aws / CDK / Terraform) stays the recommended path; `autoCreate` exists for ephemeral / dynamic-stream deployments where pre-provisioning is impractical. **Test suite**: 19 new framework-level cloudwatch assertions cover autoCreate fires both Create calls in order before PutLogEvents, ResourceAlreadyExists doesn't abort the post-create PutLogEvents, hard 5xx during CreateLogGroup drops the batch via `onDrop`, autoCreate=false skips Create calls entirely. Live syslog integration covers UDP / TCP wire delivery against the docker syslog-ng container (`/var/log/blamejs-test.log`) plus an in-process `tls.createServer` receiver that asserts the on-the-wire RFC 6587 octet-counting framing + RFC 5424 PRI / timestamp / structured-data slot the framework emits over TLS. **Test infrastructure fix**: `docker/init/generate-certs.sh` was overwriting an existing CA when re-run with `.complete` removed, invalidating every previously-issued leaf cert; now reuses an existing `(ca.crt, ca.key)` pair across `.complete`-only resets and only generates a fresh CA when neither file is present. Smoke 6790 / wiki e2e 178 / per-primitive integration 14 files (log-stream up from 16→18 checks, cloudwatch suite up from 39→58 assertions) / wiki integration 32 / shellcheck clean / eslint clean.
 - **0.6.32** (2026-05-02) — E1 from the v0.6.x scope plan. **`b.cache` Redis backend** — first-class `backend: "redis"` for `b.cache.create({...})`, no operator-supplied glue needed. New module `lib/cache-redis.js` consumes `lib/redis-client.js` directly; storage layout: `<namespace>:e:<key>` (STRING, JSON-encoded value, PEXPIREAT-bounded), `<namespace>:t:<tag>` (SET, cacheKeys carrying that tag — powers `invalidateTag` fan-out), `<namespace>:k:<key>:tags` (SET, tags this key carries — powers per-key tag cleanup on `del`/`set`-overwrite, expires alongside the entry). TTL is enforced by Redis itself (PEXPIREAT) so the framework's sweeper is a no-op for this backend; sliding TTL bumps the entry's expiry on every read when `slidingTtl: true` AND `ttlMs` is finite. New opts on `cache.create`: `redisUrl` (required when `backend: "redis"`), `redisPassword`, `redisUsername`, `redisTls`, `redisCa` (private-CA trust pinning per v0.6.28), `redisServername`, `redisConnectTimeoutMs`, `redisCommandTimeoutMs`, `redisMaxReconnectAttempts`. Concurrency: invalidateTag filters out ghost entries (key already PEXPIRE'd from the keyspace but lingering in a tag SET) by EXISTS-checking before del. Lazy connect — `cache.create({backend:"redis"})` stays sync-safe; first op opens the socket. Tests: 10 new live integration assertions on top of the existing memory + custom-backend coverage (set+get round-trip, has, del, complex JSON value round-trip, short-TTL Redis-side expiry, multi-tag invalidateTag fan-out + preservation of untagged entries, wrap() single-flight memoization through Redis). Smoke 6780 / wiki e2e 178 / per-primitive integration 14 files (cache up from 15→25 checks) / wiki integration green.
 - **0.6.31** (2026-05-02) — lazy-deferral cleanup wave from v0.6.27. **A1: queue-redis priority ordering** — `b.queue.enqueue({ priority })` on the Redis backend now matches queue-local's `ORDER BY priority DESC, availableAt ASC, enqueuedAt ASC` semantics. The Redis ZSET stays scored by availableAt only (so ZRANGEBYSCORE 0..nowMs cleanly filters ready vs not-yet-ready jobs), but `LEASE_LUA` now over-fetches `maxRows*5` candidates by score, HMGETs priority + availableAt + enqueuedAt for each, sorts server-side in Lua by the same triple queue-local sorts on, and leases the top `maxRows`. Closes the v0.6.27 deferral that punted priority ordering as "ZSET-incompatible". **A2: queue-redis flow `dependsOn` cascade** — `b.queue.enqueue({ flowId, flowChildName, dependsOn })` on the Redis backend now releases dependent jobs when their parents complete, mirroring queue-local's `_maybeReleaseFlowChildren`. A per-flow `<prefix>:flow:<flowId>` Redis SET tracks every job in the flow; `complete()` walks the set, looks up siblings whose `dependsOn` includes the just-completed job (by id OR `flowChildName`) AND every other dep is also satisfied, and HSET-bumps their `availableAt` to now + ZADDs them into the ready zset. The flow set persists across `complete()` calls so a later sibling's deps check can still find earlier-done parents by name; `purge()` cleans the set on queue teardown. Closes the v0.6.27 deferral. **A4: WebSocket per-message-deflate (RFC 7692)** — `b.websocket.handleUpgrade` negotiates the `permessage-deflate` extension when the client offers it, accepting `client_max_window_bits` / `server_max_window_bits` constraints (8-15 range, default 15) and always asserting `client_no_context_takeover` + `server_no_context_takeover` so every message uses a fresh zlib state. The connection's send path compresses TEXT/BINARY frames via `zlib.deflateRawSync`, strips the 4-byte `0x00 0x00 0xff 0xff` trailer per RFC 7692 §7.2.1, and sets RSV1 on the first frame of each compressed message. The receive path appends the trailer back and inflates via `zlib.inflateRawSync`. RSV1 on a continuation frame, RSV1 without negotiated extension, RSV2/RSV3 set, and decompressed payload exceeding `maxMessageBytes` all close with the appropriate RFC 6455 status (`PROTOCOL_ERROR`, `INVALID_PAYLOAD`, `MESSAGE_TOO_BIG`). Operator opt-out: pass `permessageDeflate: false` to `handleUpgrade` to refuse the extension even when offered. Tests cover the 101-handshake echo of negotiated params, real compression on a redundant payload (4000 bytes → ~30 bytes on the wire), uncompressed-frame round-trip on the same connection (mixed-mode per RFC 7692 §6), and unknown-extension graceful ignore. v0.6.27's third lazy deferral A3 (TLS-redis live test) was already covered by `test/integration/redis-client-tls.test.js` shipped in v0.6.28. Smoke 6780 / wiki e2e 178 / per-primitive integration 14 files green / wiki integration green.
 - **0.6.30** (2026-05-02) — wiki-app integration gate + framework follow-ups surfaced by it. **`scripts/test-wiki-integration.js`** boots `examples/wiki` against the docker-compose fixture stack (real Redis / MinIO / Mailpit / CoreDNS / NTP / mtls-ca) and drives every backend through the wiki's HTTP surface AND the underlying framework primitives — validates that each primitive routes through the configured backend (cache → custom backend, queue → Redis Streams, mail → Mailpit SMTP, object-store → MinIO sigv4, log-stream → webhook receiver) AND that every fix shipped in v0.6.28 holds in a real-app context, not just in unit-test isolation. **Wiki gains test-only routes** under `/test/*` (gated by `WIKI_INTEGRATION_TEST=1`, mounted before CSRF/staticServe so test POSTs don't have to round-trip a token cookie) covering cache get/set/del, queue enqueue/size, mail send, object-store put/get, http-client fetch, log-stream emit, mtls-ca issue, ntp query, dns lookup, ssrf classify+check, plus `/test/diagnostic` that surfaces the active backend posture (network snapshot, queue backends, log sinks, mtls algorithm). **External-integration two-gate rule** — when a release diff touches a primitive that talks to an external service (`lib/redis-client.js`, `lib/queue-redis.js`, `lib/mail.js`, `lib/network-dns.js`, `lib/object-store/*`, `lib/log-stream*.js`, `lib/external-db.js`, `lib/cluster-*.js`, `lib/mtls-ca.js`, `lib/ssrf-guard.js`, `lib/http-client.js`, `lib/ntp-check.js`, `lib/cache.js`, `lib/webhook.js`), operators MUST run BOTH `scripts/test-integration.js` (per-primitive against real backends) AND `scripts/test-wiki-integration.js` (wiki app exercising the same backends end-to-end) before pushing. Documented in CONTRIBUTING.md's pre-push gate list and CLAUDE.md's release workflow as step 4a. The smoke + wiki-e2e gates above stay PURE (no docker dependency, runs in CI / on a developer laptop / inside prepack-guard); the two-gate is operator-run, opt-in, and surfaces bugs that mocks miss — fire-and-forget races, shutdown drains, TLS pinning, real DNS resolution, real protocol handshakes. **Framework fixes surfaced by the new gate**: `b.mtlsCa.create` now auto-creates `opts.dataDir` with `mode: 0o700` if it doesn't exist (matches `b.logStream`'s local sink, `b.backup`, `b.restoreBundle` — without it the first `initCA()` call hit `ENOENT` writing `ca.key.tmp`); `b.logStream` webhook-sink `close()` now waits for the in-flight `_flush()` before draining the buffer (the v0.6.28 drain fix only tracked emit-time wrapper promises, not the actual HTTP POST in flight; a record arriving mid-flush would buffer + the emit-time `_flush` early-returned on `if (inFlight) return`, and shutdown would then strand it). `b.queue.bootFromEnv()` is now wired in the wiki app's `build-app.js` unconditionally so the wiki picks up `BLAMEJS_QUEUE_PROTOCOL=redis` from env without code changes (was previously a documented-but-commented call site). **Test architecture rule (extends the v0.6.28 rule)** — live tests for the framework's primitives go under `test/integration/`; live tests for the wiki app exercising the framework end-to-end go under `examples/wiki/test/integration.js`. Smoke (`test/smoke.js`) and the existing wiki e2e (`examples/wiki/test/e2e.js`) stay pure. Smoke / wiki-e2e green; per-primitive integration suite green; wiki integration green. Eslint pin alignment + shellcheck added to the documented gate list (carry-over from v0.6.29).

package/README.md

@@ -47,7 +47,7 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
 - **HTTP** — router with schema-validated routes + OpenAPI publication; full middleware stack (CSRF, CORS, rate-limit, security headers, CSP nonce, body parser, compression, SSE, request log, request-time DB role binding via `b.middleware.dbRoleFor`, in-process CIDR fence via `b.middleware.networkAllowlist`) wired by `createApp`; HTTP/1.1 + HTTP/2 outbound client with SSRF gate (cloud-metadata IPs hard-denied unconditionally; private / loopback / link-local overridable per call), scheme + userinfo + per-host (wildcard / per-method) destination allowlist, redirects, multipart, interceptors, progress, encrypted cookie jar (`b.httpClient`, `b.ssrfGuard`, `b.safeUrl`); operator-tunable network configurability — env-driven NTP / NTS (RFC 8915 authenticated time), IPv4-or-IPv6 NTP servers, DNS with IPv6 / DoH / DoT (private-CA trust pinning via `opts.ca`) / cache / lookup timeout, outbound HTTP proxy (`HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY`), runtime DPI trust-store CA additions, application-level heartbeats, TCP socket defaults (`b.network`).
 - **Defensive parsers** — `b.safeJson`, `b.safeBuffer`, `b.safeSql`, `b.safeSchema`, `b.parsers` (XML / TOML / YAML / .env), `b.config` (schema-validated env), `b.fileType` magic-byte content classification with deny-on-upload categories (image / document / archive / executable / etc.).
 - **Communication** — WebSockets with channel/room fan-out across cluster replicas (`b.websocket`, `b.websocketChannels`); mail with multipart + attachments + DKIM + calendar invites + bounce intake (`b.mail`, `b.mailBounce`); generic notification dispatcher with operator-supplied transports (`b.notify`).
-- **Observability** — tamper-evident audit chain with SLH-DSA-signed checkpoints, metrics, tracing (OTel pass-through when wired), PII redaction, log-stream sinks (local file rotation, generic webhook, OTLP/HTTP-JSON to an OTel collector, AWS CloudWatch Logs via SigV4), OTLP/HTTP-JSON exporter for traces + metrics (`b.audit`, `b.metrics`, `b.tracing`, `b.redact`, `b.logStream`, `b.otelExport`); operator-callable boot-time security policy assertions (`b.security.assertProduction`) and tamper-evident config-baseline drift detection signed with the audit-signing key (`b.configDrift`).
+- **Observability** — tamper-evident audit chain with SLH-DSA-signed checkpoints, metrics, tracing (OTel pass-through when wired), PII redaction, log-stream sinks (local file rotation, generic webhook, OTLP/HTTP-JSON to an OTel collector, AWS CloudWatch Logs via SigV4 with optional autoCreate, RFC 5424 syslog over UDP/TCP/TLS), OTLP/HTTP-JSON exporter for traces + metrics (`b.audit`, `b.metrics`, `b.tracing`, `b.redact`, `b.logStream`, `b.otelExport`); operator-callable boot-time security policy assertions (`b.security.assertProduction`) and tamper-evident config-baseline drift detection signed with the audit-signing key (`b.configDrift`).
 - **i18n** — CLDR plural rules, Accept-Language negotiation, Intl formatters, RTL (`b.i18n`).
 - **Format helpers** — RFC 4180 CSV with Excel formula-injection prevention (`b.csv`), RFC 9562 UUID v4 + v7 (`b.uuid`), URL-safe slugs (`b.slug`), TZ-aware datetime (`b.time`), ZIP creation (`b.archive`), HMAC-signed cursor pagination (`b.pagination`), HTML form rendering + validation + CSRF (`b.forms`).
 - **Production** — cluster leader election with fenced leases over Postgres/SQLite (`b.cluster`); cron + interval scheduler that runs exactly-once globally (`b.scheduler`); retry with full-jitter backoff + circuit breaker (`b.retry`); graceful shutdown (`b.appShutdown`); NTP boot check (`b.ntpCheck`); end-to-end-encrypted backup bundles with pre-flush fail-closed mode (`b.backup`); restore with pulled-bundle footprint preflight (`b.restore`); GDPR / PCI / HIPAA-shaped retention rules with multi-stage warn → archive → erase, legal-hold exemptions, dry-run preview, cross-table cascade (`b.retention`).

package/lib/log-stream-cloudwatch.js

@@ -87,12 +87,13 @@ function _serializeBatch(events, cfg, sequenceToken) {
   return Buffer.from(JSON.stringify(body), "utf8");
 }
 
-function _signedHeaders(cfg, body) {
+function _signedHeaders(cfg, body, target) {
+  target = target || "Logs_20140328.PutLogEvents";
   var url = _resolveEndpoint(cfg);
   var payloadHash = nodeCrypto.createHash("sha256").update(body).digest("hex");
   var unsigned = {
     "Content-Type": "application/x-amz-json-1.1",
-    "X-Amz-Target": "Logs_20140328.PutLogEvents",
+    "X-Amz-Target": target,
   };
   var signed = sigv4.signRequest({
     method:          "POST",
@@ -108,6 +109,41 @@ function _signedHeaders(cfg, body) {
   return signed.headers;
 }
 
+// CloudWatch CreateLogGroup / CreateLogStream wrappers. Operator opts in
+// via cfg.autoCreate = true; default stays "operator pre-creates via
+// Terraform / CDK / aws cli" so the framework doesn't paper over an
+// IAM-misconfigured deployment with surprising side effects.
+async function _ensureLogGroupAndStream(cfg) {
+  // CreateLogGroup — idempotent on the wire (we treat
+  // ResourceAlreadyExistsException as success).
+  var groupBody = Buffer.from(JSON.stringify({ logGroupName: cfg.logGroupName }), "utf8");
+  var groupHeaders = _signedHeaders(cfg, groupBody, "Logs_20140328.CreateLogGroup");
+  try {
+    await _post(cfg, groupBody, groupHeaders);
+  } catch (e) {
+    var msg = (e && e.message) || "";
+    if (!/ResourceAlreadyExistsException/.test(msg)) {
+      throw _err("AUTOCREATE_FAILED",
+        "log-stream cloudwatch autoCreate: CreateLogGroup failed: " + msg);
+    }
+  }
+  // CreateLogStream — same idempotency treatment.
+  var streamBody = Buffer.from(JSON.stringify({
+    logGroupName:  cfg.logGroupName,
+    logStreamName: cfg.logStreamName,
+  }), "utf8");
+  var streamHeaders = _signedHeaders(cfg, streamBody, "Logs_20140328.CreateLogStream");
+  try {
+    await _post(cfg, streamBody, streamHeaders);
+  } catch (e) {
+    var msg2 = (e && e.message) || "";
+    if (!/ResourceAlreadyExistsException/.test(msg2)) {
+      throw _err("AUTOCREATE_FAILED",
+        "log-stream cloudwatch autoCreate: CreateLogStream failed: " + msg2);
+    }
+  }
+}
+
 function _post(cfg, body, headers) {
   return httpClient.request({
     method:           "POST",
@@ -144,9 +180,11 @@ function create(config) {
   }
   if (!config.logGroupName || !config.logStreamName) {
     throw _err("BAD_OPT",
-      "log-stream cloudwatch requires { logGroupName, logStreamName } " +
-      "(operator pre-creates both via aws logs create-log-group / create-log-stream " +
-      "or CDK / Terraform; the framework does NOT auto-create)");
+      "log-stream cloudwatch requires { logGroupName, logStreamName }. " +
+      "Operator pre-creates both via aws / CDK / Terraform by default; " +
+      "pass { autoCreate: true } to have the framework issue " +
+      "CreateLogGroup + CreateLogStream on first emit (idempotent — " +
+      "ResourceAlreadyExistsException treated as success).");
   }
   var cfg = Object.assign({}, DEFAULTS, config);
   var onDrop = typeof cfg.onDrop === "function" ? cfg.onDrop : null;
@@ -186,11 +224,32 @@ function create(config) {
     return batch;
   }
 
+  // autoCreate handshake — runs once per process before the first
+  // PutLogEvents. Promise cached so concurrent emits don't fire
+  // duplicate CreateLogGroup / CreateLogStream calls.
+  var autoCreatePromise = null;
+  function _ensureAutoCreated() {
+    if (!cfg.autoCreate) return Promise.resolve();
+    if (!autoCreatePromise) autoCreatePromise = _ensureLogGroupAndStream(cfg);
+    return autoCreatePromise;
+  }
+
   async function _flush() {
     if (inFlight) return;
     if (buffer.length === 0) return;
     inFlight = true;
     try {
+      try { await _ensureAutoCreated(); }
+      catch (acErr) {
+        // autoCreate failure is permanent — every subsequent batch
+        // would hit the same error. Drop the queue with the
+        // operator-supplied onDrop callback so they see exactly which
+        // events were lost AND why, then bail.
+        var allBuffered = buffer.splice(0, buffer.length);
+        dropCount += allBuffered.length;
+        _emitDrop("autocreate-failed", allBuffered, acErr);
+        return;
+      }
       while (buffer.length > 0 && !closed) {
         var batch = _takeBatch();
         if (batch.length === 0) break;

package/lib/log-stream-syslog.js

@@ -0,0 +1,297 @@
+"use strict";
+/**
+ * Syslog log-stream sink — RFC 5424 framing over UDP / TCP / TLS.
+ *
+ * Wire format (RFC 5424 §6):
+ *   <PRI>VERSION SP TIMESTAMP SP HOSTNAME SP APP-NAME SP PROCID SP MSGID SP STRUCTURED-DATA SP MSG
+ *
+ *   PRI    = (facility * 8) + severity
+ *   facility (default 16 = local0; 1 = user — operators commonly pick
+ *            local0..local7 for app-emitted records)
+ *   severity is mapped from the framework's level field:
+ *     debug → 7, info → 6, warn → 4, error → 3
+ *
+ * Transport:
+ *   udp                — single datagram per record (no framing)
+ *   tcp                — octet-counting framing (RFC 6587 §3.4.1):
+ *                        "<length> <message>" with a SPACE between
+ *                        length and the rfc5424 message bytes
+ *   tls                — same octet-counting framing on a TLS socket
+ *                        (RFC 5425). Standard port 6514.
+ *
+ * Defaults match RFC 3164/5424 conventions: appName = "blamejs",
+ * facility = local0 (16), hostname = os.hostname(), structuredData = "-".
+ *
+ * Flow control:
+ *   The TCP / TLS variants buffer pending writes during socket
+ *   reconnect and replay them on the new connection. UDP is best-effort
+ *   (datagrams that race a closed socket are dropped to onDrop).
+ */
+var dgram = require("dgram");
+var net   = require("net");
+var os    = require("os");
+var tls   = require("tls");
+var C = require("./constants");
+var { LogStreamError } = require("./framework-error");
+
+var _err = LogStreamError.factory;
+
+var DEFAULT_FACILITY    = 16;          // local0
+var DEFAULT_APP_NAME    = "blamejs";
+var DEFAULT_PROC_ID     = String(process.pid);
+var DEFAULT_MSG_ID      = "-";
+var DEFAULT_STRUCT_DATA = "-";
+var TCP_DEFAULT_PORT    = 514;
+var TLS_DEFAULT_PORT    = 6514;
+var UDP_DEFAULT_PORT    = 514;
+var DEFAULT_TIMEOUT_MS  = C.TIME.seconds(10);
+var DEFAULT_RECONNECT_BASE_MS = 250;
+var DEFAULT_RECONNECT_MAX_MS  = 30000;
+var DEFAULT_BUFFER_LIMIT = 10000;
+
+// RFC 5424 severity codes from the framework's level names.
+var LEVEL_TO_SEVERITY = {
+  debug: 7,
+  info:  6,
+  warn:  4,
+  error: 3,
+};
+
+function _toRfc3339(tsMs) {
+  return new Date(tsMs).toISOString();
+}
+
+function _formatRfc5424(record, cfg) {
+  var severity = LEVEL_TO_SEVERITY[record.level] != null
+    ? LEVEL_TO_SEVERITY[record.level] : 6;
+  var pri = (cfg.facility * 8) + severity;
+  var ts  = _toRfc3339(record.ts || Date.now());
+  // Body — JSON-encode meta + message together so the structured
+  // payload survives the wire as a single MSG token. Operators with
+  // their own RFC 5424 STRUCTURED-DATA producers pass cfg.structuredData
+  // (string) to override the default "-".
+  var body = record.message || "";
+  if (record.meta && Object.keys(record.meta).length > 0) {
+    try { body += " " + JSON.stringify(record.meta); }
+    catch (_e) { /* best-effort */ }
+  }
+  return "<" + pri + ">1 " + ts + " " + cfg.hostname + " " +
+         cfg.appName + " " + cfg.procId + " " + cfg.msgId + " " +
+         (cfg.structuredData || "-") + " " + body;
+}
+
+function create(config) {
+  if (!config) throw _err("BAD_OPT", "log-stream syslog requires { url } (e.g. udp://host:514, tcp://host:514, tls://host:6514)");
+  var url = config.url;
+  if (typeof url !== "string" || url.length === 0) {
+    throw _err("BAD_OPT", "log-stream syslog requires { url } (string)");
+  }
+  // Parse URL — accept udp://, tcp://, tls://. safeUrl rejects http://
+  // by default; allow these explicit transports.
+  var parsed;
+  try {
+    parsed = new URL(url);
+  } catch (e) {
+    throw _err("BAD_URL", "log-stream syslog: bad url '" + url + "': " +
+      ((e && e.message) || String(e)));
+  }
+  var transport = parsed.protocol.replace(/:$/, "").toLowerCase();
+  if (transport !== "udp" && transport !== "tcp" && transport !== "tls") {
+    throw _err("BAD_URL",
+      "log-stream syslog: protocol must be udp / tcp / tls, got " +
+      JSON.stringify(parsed.protocol));
+  }
+  var defaultPort = transport === "tls" ? TLS_DEFAULT_PORT
+                  : transport === "tcp" ? TCP_DEFAULT_PORT
+                  : UDP_DEFAULT_PORT;
+  var host = parsed.hostname;
+  var port = parsed.port ? parseInt(parsed.port, 10) : defaultPort;
+
+  var cfg = {
+    transport:        transport,
+    host:             host,
+    port:             port,
+    facility:         (typeof config.facility === "number" && config.facility >= 0 && config.facility <= 23)
+                        ? Math.floor(config.facility) : DEFAULT_FACILITY,
+    appName:          config.appName || DEFAULT_APP_NAME,
+    procId:           config.procId  || DEFAULT_PROC_ID,
+    msgId:            config.msgId   || DEFAULT_MSG_ID,
+    hostname:         config.hostname || os.hostname(),
+    structuredData:   config.structuredData || DEFAULT_STRUCT_DATA,
+    timeoutMs:        config.timeoutMs || DEFAULT_TIMEOUT_MS,
+    bufferLimit:      config.bufferLimit || DEFAULT_BUFFER_LIMIT,
+    reconnectBaseMs:  config.reconnectBaseMs || DEFAULT_RECONNECT_BASE_MS,
+    reconnectMaxMs:   config.reconnectMaxMs  || DEFAULT_RECONNECT_MAX_MS,
+    ca:               config.ca || null,
+    rejectUnauthorized: config.rejectUnauthorized !== false,
+    servername:       config.servername || null,
+  };
+  // safeUrl-style guard for the URL — reject userinfo (no auth in
+  // syslog wire) so a stray "syslog://user:pw@host" doesn't silently
+  // get through.
+  if (parsed.username || parsed.password) {
+    throw _err("BAD_URL",
+      "log-stream syslog: url must not contain userinfo");
+  }
+  // Track the operator's onDrop so dropped events surface.
+  var onDrop = typeof config.onDrop === "function" ? config.onDrop : null;
+  function _emitDrop(reason, batch, err) {
+    if (!onDrop) return;
+    try { onDrop({ reason: reason, batch: batch, error: err || null }); }
+    catch (_e) {}
+  }
+
+  // ---- UDP transport ----
+  if (transport === "udp") {
+    var udpFamily = host.indexOf(":") !== -1 ? "udp6" : "udp4";
+    var udpSock = dgram.createSocket(udpFamily);
+    udpSock.unref && udpSock.unref();
+    var udpClosed = false;
+    udpSock.on("error", function () { /* non-fatal — datagrams race */ });
+
+    return {
+      protocol: "syslog-udp",
+      emit: function (record) {
+        if (udpClosed) {
+          _emitDrop("sink-closed", [record], null);
+          return Promise.resolve({ accepted: false, reason: "closed" });
+        }
+        var msg = _formatRfc5424(record, cfg);
+        var buf = Buffer.from(msg, "utf8");
+        return new Promise(function (resolve) {
+          udpSock.send(buf, 0, buf.length, cfg.port, cfg.host, function (err) {
+            if (err) _emitDrop("udp-send-error", [record], err);
+            resolve({ accepted: !err, queued: 0 });
+          });
+        });
+      },
+      close: function () {
+        udpClosed = true;
+        try { udpSock.close(); } catch (_e) {}
+        return Promise.resolve();
+      },
+    };
+  }
+
+  // ---- TCP / TLS transport — octet-counting framing (RFC 6587) ----
+  // Buffer outgoing records during socket-down windows; replay on
+  // reconnect. Operator opts: bufferLimit caps the queue; oldest
+  // dropped first with the onDrop "overflow" reason.
+  var sock = null;
+  var sockReady = false;
+  var connecting = false;
+  var queue = [];
+  var closed = false;
+  var reconnectAttempt = 0;
+
+  function _writeFramed(record) {
+    var msg = _formatRfc5424(record, cfg);
+    var msgBuf = Buffer.from(msg, "utf8");
+    var prefix = Buffer.from(msgBuf.length + " ", "utf8");
+    sock.write(Buffer.concat([prefix, msgBuf]));
+  }
+
+  function _connect() {
+    if (closed || connecting) return;
+    connecting = true;
+    sockReady = false;
+    var connectOpts = { host: cfg.host, port: cfg.port };
+    var onConnect = function () {
+      connecting = false;
+      sockReady = true;
+      reconnectAttempt = 0;
+      // Drain queue in arrival order on (re)connect.
+      while (queue.length > 0 && sockReady) {
+        try { _writeFramed(queue.shift()); }
+        catch (e) { _emitDrop("write-error", [/* drained */], e); break; }
+      }
+    };
+    if (transport === "tls") {
+      var tlsOpts = Object.assign({}, connectOpts, {
+        rejectUnauthorized: cfg.rejectUnauthorized,
+        minVersion:         "TLSv1.3",
+      });
+      if (cfg.ca) tlsOpts.ca = cfg.ca;
+      if (cfg.servername) tlsOpts.servername = cfg.servername;
+      sock = tls.connect(tlsOpts, onConnect);
+    } else {
+      sock = net.connect(connectOpts, onConnect);
+    }
+    sock.unref && sock.unref();
+    sock.on("error", function () { /* defer to 'close' for reconnect */ });
+    sock.on("close", function () {
+      sockReady = false;
+      connecting = false;
+      try { sock.destroy(); } catch (_e) {}
+      sock = null;
+      if (closed) return;
+      reconnectAttempt += 1;
+      var delay = Math.min(cfg.reconnectMaxMs,
+        cfg.reconnectBaseMs * Math.pow(2, reconnectAttempt - 1));
+      var t = setTimeout(_connect, delay);
+      t.unref && t.unref();
+    });
+  }
+  _connect();
+
+  return {
+    protocol: "syslog-" + transport,
+    emit: function (record) {
+      if (closed) {
+        _emitDrop("sink-closed", [record], null);
+        return Promise.resolve({ accepted: false, reason: "closed" });
+      }
+      if (sockReady) {
+        try { _writeFramed(record); }
+        catch (e) {
+          _emitDrop("write-error", [record], e);
+          return Promise.resolve({ accepted: false, reason: "write-error" });
+        }
+        return Promise.resolve({ accepted: true, queued: 0 });
+      }
+      // Socket not yet up — buffer with overflow-by-oldest semantics.
+      if (queue.length >= cfg.bufferLimit) {
+        var dropped = queue.shift();
+        _emitDrop("overflow", [dropped], null);
+      }
+      queue.push(record);
+      return Promise.resolve({ accepted: true, queued: queue.length });
+    },
+    close: function () {
+      // Give an in-flight (re)connect a brief window to complete and
+      // drain the buffer. Without this, records emitted just before
+      // shutdown race the slower TLS handshake and surface as
+      // "sink-closed" drops even though the framework had a viable
+      // connection in progress.
+      var DRAIN_TIMEOUT_MS = 3000;
+      var started = Date.now();
+      return new Promise(function (resolve) {
+        function _finish() {
+          closed = true;
+          var pending = queue.splice(0, queue.length);
+          if (pending.length > 0) _emitDrop("sink-closed", pending, null);
+          try { if (sock) sock.end(); } catch (_e) {}
+          try { if (sock) sock.destroy(); } catch (_e) {}
+          sock = null;
+          resolve();
+        }
+        function _tick() {
+          if (queue.length === 0 || Date.now() - started > DRAIN_TIMEOUT_MS) {
+            return _finish();
+          }
+          // Keep the timer ref'd — close() is being awaited; if we
+          // unref the drain-tick timer the event loop can exit between
+          // ticks (UDP/TCP socket are also unref'd) and the close
+          // promise pends forever silently.
+          setTimeout(_tick, 25);
+        }
+        _tick();
+      });
+    },
+    // Test-only: returns the in-flight queue size for assertions.
+    _queueSizeForTest: function () { return queue.length; },
+    _formatRfc5424ForTest: function (rec) { return _formatRfc5424(rec, cfg); },
+  };
+}
+
+module.exports = { create: create };

package/lib/log-stream.js

@@ -15,15 +15,15 @@
  *              (k8s, cloud) get standard log forwarding without a
  *              vendor-specific adapter.
  *   cloudwatch — AWS CloudWatch Logs (PutLogEvents) over HTTPS with
- *              SigV4. Operator pre-creates the log group + log stream;
- *              the framework signs and POSTs batches respecting the
- *              10K-event / 1 MiB / 256 KiB-per-event AWS caps. Honors
- *              IAM role + STS session tokens.
- *
- * Adapters listed as deferred and surfacing a clear error when
- * selected:
- *
- *   syslog — RFC 5424 syslog over TLS
+ *              SigV4. Pass { autoCreate: true } to have the framework
+ *              issue CreateLogGroup + CreateLogStream on first emit
+ *              (idempotent — ResourceAlreadyExistsException treated as
+ *              success). Honors IAM role + STS session tokens. Respects
+ *              the 10K-event / 1 MiB / 256 KiB-per-event AWS caps.
+ *   syslog   — RFC 5424 with octet-counting framing over UDP / TCP /
+ *              TLS. UDP is best-effort; TCP/TLS buffer during socket
+ *              reconnect and replay on connect. Default ports 514
+ *              (UDP/TCP) and 6514 (TLS).
  *
  * Every emit goes through lib/redact.js BEFORE any sink sees it. PHI/PCI
  * never reaches operational logs even on a misconfigured field name —
@@ -50,6 +50,7 @@ var localProto      = require("./log-stream-local");
 var webhookProto    = require("./log-stream-webhook");
 var otlpProto       = require("./log-stream-otlp");
 var cloudwatchProto = require("./log-stream-cloudwatch");
+var syslogProto     = require("./log-stream-syslog");
 var redactor        = require("./redact");
 var lazyRequire     = require("./lazy-require");
 var protocolDispatcher = require("./protocol-dispatcher");
@@ -63,10 +64,9 @@ var dispatcher = protocolDispatcher.create({
     "webhook":    webhookProto,
     "otlp":       otlpProto,
     "cloudwatch": cloudwatchProto,
+    "syslog":     syslogProto,
   },
-  deferred:   {
-    "syslog":     { description: "RFC 5424 syslog over TLS" },
-  },
+  deferred:   {},
   fallbackProtocol: "local",
 });
 

package/lib/protocol-dispatcher.js

@@ -5,7 +5,7 @@
  *
  * Three framework modules ship a "pick a backend by protocol name" surface:
  *   - lib/queue.js                 (local, deferred: redis/sqs/amqp/nats)
- *   - lib/log-stream.js            (local + webhook, deferred: syslog/otlp/cloudwatch)
+ *   - lib/log-stream.js            (local + webhook + otlp + cloudwatch + syslog)
  *   - lib/object-store/index.js    (local + http-put + sigv4 + gcs + azure-blob)
  *
  * Each previously copied a ~30-line dispatch block: validate config has a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.6.32",
+  "version": "0.6.33",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cyclonedx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:bf737d55-37d5-49a4-95fb-c1149d627468",
+  "serialNumber": "urn:uuid:c1b1caea-6dd0-463e-8c6d-2490abcb0c2e",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-02T19:10:22.247Z",
+    "timestamp": "2026-05-02T19:44:37.593Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.6.32",
+      "bom-ref": "@blamejs/core@0.6.33",
       "type": "library",
       "name": "blamejs",
-      "version": "0.6.32",
+      "version": "0.6.33",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.6.32",
+      "purl": "pkg:npm/%40blamejs/core@0.6.33",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.6.32",
+      "ref": "@blamejs/core@0.6.33",
       "dependsOn": []
     }
   ]