@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.
• 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.

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.

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"'