@libreflare/worker-runtime

Shared runtime utilities for Libreflare-managed Cloudflare Workers.

Package Contents

• handleRequest: batched logging request handler for managed logging Workers.
• handleLibreflareRequest: generated-config route/logging request handler. Pass runtimeConfig from a generated JSON import, or rely on the legacy LIBREFLARE_CONFIG env binding. For route-only v2 config, pass apiURL, getSourceKey, apiAuthHeaders, and related options to keep logging owned by the Worker repository.
• evaluateExpression: Cloudflare Rules expression evaluator for Worker-side diagnostics. Unresolved Cloudflare list references are inferred as matches by default and can be disabled via options.
• analyzeRuleExpression: versioned, JSON-safe Cloudflare Rules AST, symbol metadata, and optional block-comment metadata for dashboard inference.
• foldRuleExpressionAst: bottom-up public AST reducer for custom dashboard inference.
• getRuleExpressionFieldDescriptions: field descriptions filtered by the same preset and field availability override shape used by rule expression validation.
• getRuleExpressionFunctionDescriptions: function reference metadata for dashboard editors, including signatures, return types, parameter roles, and evaluator support notes.
• minifyRuleExpression: whitespace minifier for Cloudflare Rules expressions before Rewrite Rule deployment.
• validateRuleExpressionSyntax: syntax, length, and field availability validation for Cloudflare URL Rewrite Rule filter expressions by default. Pass an explicit config object for minification, length, preset, field availability, deprecated-field notices, and list-reference policy. With minification enabled it validates the minified expression against Cloudflare's 4096-character rule limit by default; when minification is disabled, the result omits minifiedExpression and minifiedLength.

Rule expression validation, analysis, and minification expose structured diagnostics with stable id, explicit severity, and interpolation params for localization. The diagnostic message is an optional, deprecated compatibility field. The legacy errors and warnings string arrays on validation results, and warnings on analysis/minification results, are also deprecated compatibility fields; new integrations should derive user-visible messages from diagnostic IDs and params.

handleRequest calls that provide a custom originFetcher without stripWorkerRoutePrefix are deprecated. When stripWorkerRoutePrefix is configured, origin fetching and rule evaluation both use the stripped origin URL.

Set resolveClientHostname: true in handler options or managed logging runtime config to add request.client_hostname to log events. The runtime performs a bounded reverse DNS lookup for the cf-connecting-ip header during the existing background logging work and caches resolved hostnames per Worker isolate.

Development

npm install
npm run build:field-descriptions
npm run build:function-descriptions
npm run build
npm run typecheck
npm test
npm pack --dry-run

The package emits publishable files to dist/. Publishing is configured for restricted scoped package access.

To diagnose why an expression does not match a captured request log:

npm run explain:rule -- --sample <log-json-path> --expr 'http.host eq "example.com"'

Rule parser/evaluator refactor notes are tracked in docs/rule-evaluator-refactor.md.