@dunx/http 3.5.1 → 3.7.0

package/README.md

@@ -62,13 +62,16 @@ The guide is canonical for every row; this table is the index.
 | Typed input             | `body`, `query`, `params` over Standard Schema              | [Validation](../../docs/guide/06-validation.md)                   |
 | Middleware and guards   | One extension point, `@UseGuards`, `@Roles`, `@Public`      | [Middleware and guards](../../docs/guide/08-middleware-and-guards.md) |
 | WebSocket gateways      | `@Gateway`, handlers, `PubSub`, multi-node relay            | [WebSockets](../../docs/guide/09-websockets.md)                   |
+| Server-sent events      | `@Sse`, `SseStream`, framing, heartbeats, `Last-Event-ID`   | [Controllers](../../docs/guide/05-controllers.md)                 |
 | Request logging         | One structured entry per request, on by default             | [Logging](../../docs/guide/13-logging.md)                         |
 | Trace context           | W3C `traceparent` adopted and propagated, on by default     | [Logging](../../docs/guide/13-logging.md)                         |
-| Metrics                 | Per-route counts and timings, off by default                | [Metrics](../../docs/guide/22-metrics.md)                         |
-| Health and draining     | `/health/live`, `/health/ready`, readiness during a rollout | [Health checks](../../docs/guide/20-health-checks.md)             |
+| Metrics                 | Per-route counts and timings, off by default                | [Metrics](../../docs/guide/23-metrics.md)                         |
+| Health and draining     | `/health/live`, `/health/ready`, readiness during a rollout | [Health checks](../../docs/guide/21-health-checks.md)             |
 | Throttling              | `@Throttle`, `@SkipThrottle`, memory and Redis counters     | [Middleware and guards](../../docs/guide/08-middleware-and-guards.md) |
-| Static files            | `Bun.file` behind a mount, with a cache policy              | [Deployment](../../docs/guide/19-deployment.md)                   |
-| Compression             | zstd and gzip on Bun's own compressors                      | [Deployment](../../docs/guide/19-deployment.md)                   |
+| Outbound resilience     | `HttpRetryClassifier`: which statuses retry, and `Retry-After` | [Resilience](../../docs/guide/25-resilience.md)                |
+| Static files            | `Bun.file` behind a mount, with a cache policy              | [Deployment](../../docs/guide/20-deployment.md)                   |
+| Compression             | zstd and gzip on Bun's own compressors                      | [Deployment](../../docs/guide/20-deployment.md)                   |
+| RPC                     | protobuf over Connect and gRPC-Web, as middleware           | [RPC](../../docs/guide/27-rpc.md)                                 |
 
 ## Subpaths
 
@@ -76,6 +79,7 @@ The guide is canonical for every row; this table is the index.
 | ---------------------- | ----------------------------------------------------------------- |
 | `@dunx/http`           | Everything above                                                  |
 | `@dunx/http/client`    | The outbound half: `HttpService`, retry with backoff, `HttpModule` |
+| `@dunx/http/connect`   | protobuf services over Connect and gRPC-Web, mounted as middleware |
 | `@dunx/http/internal`  | The framework's own plumbing. No stability promise                |
 
 `@dunx/http/internal` holds route-table construction, the middleware fold, the
@@ -100,6 +104,12 @@ from, and it may change in any release.
   ns. W3C Trace Context is the only correlation id; there is no second one.
 - `metrics: true` adds per-route counts and a nanosecond histogram at +35.2 ns a
   request, folded into the `.then` request logging already allocates.
+- `@dunx/http/connect` serves Connect and gRPC-Web, not native gRPC. gRPC carries
+  `grpc-status` in an HTTP trailer and `Bun.serve` sends no trailers, so a request
+  with `content-type: application/grpc` gets a 415 that says so.
+  `@connectrpc/connect` and `@bufbuild/protobuf` are optional peers, and the
+  `.proto` toolchain stays yours. `ThrottleGuard` does not cover an RPC: it skips
+  every unmatched path, and an RPC path is in no route table.
 
 ## License
 

package/dist/chunk-08k9vq31.js

@@ -0,0 +1,94 @@
+// @bun
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __name = (target, name) => {
+  Object.defineProperty(target, "name", {
+    value: name,
+    enumerable: false,
+    configurable: true
+  });
+  return target;
+};
+var __knownSymbol = (name, symbol) => (symbol = Symbol[name]) ? symbol : Symbol.for("Symbol." + name);
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
+var __defNormalProp = (obj, key, value) => (key in obj) ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
+var __privateIn = (member, obj) => Object(obj) !== obj ? __typeError('Cannot use the "in" operator on this value') : member.has(obj);
+var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
+var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
+var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
+var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
+var __decoratorStart = (base) => [, , , __create(base?.[__knownSymbol("metadata")] ?? null)];
+var __decoratorStrings = ["class", "method", "getter", "setter", "accessor", "field", "value", "get", "set"];
+var __expectFn = (fn) => fn !== undefined && typeof fn !== "function" ? __typeError("Function expected") : fn;
+var __decoratorContext = (kind, name, done, metadata, fns) => ({
+  kind: __decoratorStrings[kind],
+  name,
+  metadata,
+  addInitializer: (fn) => done._ ? __typeError("Already initialized") : fns.push(__expectFn(fn || null))
+});
+var __decoratorMetadata = (array, target) => __defNormalProp(target, __knownSymbol("metadata"), array[3]);
+var __runInitializers = (array, flags, self, value) => {
+  for (var i = 0, fns = array[flags >> 1], n = fns && fns.length;i < n; i++)
+    flags & 1 ? fns[i].call(self) : value = fns[i].call(self, value);
+  return value;
+};
+var __decorateElement = (array, flags, name, decorators, target, extra) => {
+  var fn, it, done, ctx, access, k = flags & 7, s = !!(flags & 8), p = !!(flags & 16);
+  var j = k > 3 ? array.length + 1 : k ? s ? 1 : 2 : 0, key = __decoratorStrings[k + 5];
+  var initializers = k > 3 && (array[j - 1] = []), extraInitializers = array[j] || (array[j] = []);
+  var desc = k && (!p && !s && (target = target.prototype), k < 5 && (k > 3 || !p) && __getOwnPropDesc(k < 4 ? target : {
+    get [name]() {
+      return __privateGet(this, extra);
+    },
+    set [name](x) {
+      __privateSet(this, extra, x);
+    }
+  }, name));
+  k ? p && k < 4 && __name(extra, (k > 2 ? "set " : k > 1 ? "get " : "") + name) : __name(target, name);
+  for (var i = decorators.length - 1;i >= 0; i--) {
+    ctx = __decoratorContext(k, name, done = {}, array[3], extraInitializers);
+    if (k) {
+      ctx.static = s, ctx.private = p, access = ctx.access = { has: p ? (x) => __privateIn(target, x) : (x) => (name in x) };
+      if (k ^ 3)
+        access.get = p ? (x) => (k ^ 1 ? __privateGet : __privateMethod)(x, target, k ^ 4 ? extra : desc.get) : (x) => x[name];
+      if (k > 2)
+        access.set = p ? (x, y) => __privateSet(x, target, y, k ^ 4 ? extra : desc.set) : (x, y) => x[name] = y;
+    }
+    it = (0, decorators[i])(k ? k < 4 ? p ? extra : desc[key] : k > 4 ? undefined : { get: desc.get, set: desc.set } : target, ctx);
+    done._ = 1;
+    if (k ^ 4 || it === undefined)
+      __expectFn(it) && (k > 4 ? initializers.unshift(it) : k ? p ? extra = it : desc[key] = it : target = it);
+    else if (typeof it !== "object" || it === null)
+      __typeError("Object expected");
+    else
+      __expectFn(fn = it.get) && (desc.get = fn), __expectFn(fn = it.set) && (desc.set = fn), __expectFn(fn = it.init) && initializers.unshift(fn);
+  }
+  return k || __decoratorMetadata(array, target), desc && __defProp(target, name, desc), p ? k ^ 4 ? extra : desc : target;
+};
+
+// src/route/claims.ts
+import { AppError } from "@dunx/core";
+
+class PathClaims {
+  #owners = new Map;
+  #noun;
+  #remedy;
+  constructor(noun, remedy) {
+    this.#noun = noun;
+    this.#remedy = remedy;
+  }
+  claim(key, owner) {
+    const existing = this.#owners.get(key);
+    if (existing !== undefined) {
+      throw new AppError(`${this.#noun} collision: ${key} is declared by ${existing} and by ` + `${owner}. ${this.#remedy}`);
+    }
+    this.#owners.set(key, owner);
+  }
+}
+Object.defineProperty(PathClaims, Symbol.for("dunx.deps"), { value: () => [{ unresolved: "noun: string" }, { unresolved: "remedy: string" }] });
+
+export { __privateGet, __privateAdd, __decoratorStart, __decoratorMetadata, __runInitializers, __decorateElement, PathClaims };

package/dist/{chunk-p9hdmkm6.js → chunk-1jt27yka.js}

@@ -40,6 +40,8 @@ var ROLES2 = metaKey2("roles");
 var PUBLIC2 = metaKey2("public");
 var HIDDEN2 = metaKey2("hidden");
 var UNMATCHED2 = metaKey2("unmatched");
+var STREAMS2 = metaKey2("streams");
+var REQUEST_SERVER = metaKey2("request-server");
 var Roles2 = (...roles) => meta2(ROLES2, roles);
 var Public2 = () => meta2(PUBLIC2, true);
 var ApiHidden2 = () => meta2(HIDDEN2, true);
@@ -90,6 +92,11 @@ var discoverRoutes2 = (instance) => {
 };
 
 // src/route/prefix.ts
+var normalizePrefix = (path) => {
+  const trimmed = path.split("/").filter(Boolean).join("/");
+  return trimmed === "" ? "/" : `/${trimmed}`;
+};
+
 class RoutePrefix2 {
   #value = "";
   get value() {
@@ -103,86 +110,4 @@ class RoutePrefix2 {
   }
 }
 
-// src/ws/marker.ts
-var HANDLER = Symbol.for("dunx.ws.handler");
-var GATEWAY = Symbol.for("dunx.ws.gateway");
-var HandlerKind = Object.freeze({
-  UPGRADE: "upgrade",
-  OPEN: "open",
-  MESSAGE: "message",
-  CLOSE: "close",
-  DRAIN: "drain",
-  PING: "ping",
-  PONG: "pong"
-});
-var markHandler = (target, meta) => {
-  Object.defineProperty(target, HANDLER, { value: meta, configurable: true });
-};
-var handlerMetaOf = (value) => typeof value === "function" ? value[HANDLER] : undefined;
-var markGateway = (target, path) => {
-  Object.defineProperty(target, GATEWAY, { value: path, configurable: true });
-};
-var gatewayPathOf = (target) => target[GATEWAY] ?? "/";
-var isGateway2 = (target) => target[GATEWAY] !== undefined;
-
-// src/server/context.ts
-var EMPTY = new Map;
-var buildContext2 = (route) => {
-  const record = route.meta ?? EMPTY;
-  return Object.freeze({
-    controller: route.controller,
-    handler: route.handlerName,
-    method: route.method,
-    path: route.path,
-    parsesBody: route.options?.body !== undefined,
-    get: (key) => record.get(key.id)
-  });
-};
-
-// src/ws/discover.ts
-import {
-  AppError,
-  classOf,
-  markedMethods as markedMethods2
-} from "@dunx/core";
-var normalizePath = (path) => {
-  const joined = `/${path}`.replace(/\/{2,}/g, "/");
-  return joined.length > 1 ? joined.replace(/\/$/, "") : "/";
-};
-var eachHandler = (start) => markedMethods2(start, handlerMetaOf);
-var discoverGateway = (instance) => {
-  const klass = instance.constructor;
-  const members = instance;
-  return {
-    name: klass.name,
-    path: normalizePath(gatewayPathOf(klass)),
-    handlers: eachHandler(Object.getPrototypeOf(instance)).map(({ name, meta }) => ({
-      kind: meta.kind,
-      event: meta.event,
-      method: name,
-      invoke: members[name].bind(instance)
-    }))
-  };
-};
-var findHandlerMethod = (ctor) => eachHandler(ctor.prototype)[0]?.name;
-var discoverGateways = (modules, resolve) => {
-  const discovered = [];
-  for (const module of modules) {
-    for (const entry of module.options.providers ?? []) {
-      const candidate = classOf(entry);
-      if (!candidate)
-        continue;
-      if (isGateway2(candidate.ctor)) {
-        discovered.push(discoverGateway(resolve(candidate.token)));
-        continue;
-      }
-      const orphan = findHandlerMethod(candidate.ctor);
-      if (orphan !== undefined) {
-        throw new AppError(`${candidate.ctor.name}.${orphan}() is a websocket handler, but ` + `${candidate.ctor.name} is not a gateway. Decorate the class with ` + "@Gateway(path), or drop the handler decorator.");
-      }
-    }
-  }
-  return discovered;
-};
-
-export { defaultStatusFor2, markRoute, markController, metaKey2, meta2, ROLES2, PUBLIC2, HIDDEN2, UNMATCHED2, Roles2, Public2, ApiHidden2, UseGuards2, metaOf2, mergeMeta2, joinPath2, discoverRoutes2, RoutePrefix2, HandlerKind, markHandler, markGateway, isGateway2, discoverGateway, discoverGateways, buildContext2 };
+export { defaultStatusFor2, markRoute, markController, metaKey2, meta2, ROLES2, PUBLIC2, HIDDEN2, UNMATCHED2, STREAMS2, REQUEST_SERVER, Roles2, Public2, ApiHidden2, UseGuards2, metaOf2, mergeMeta2, joinPath2, discoverRoutes2, normalizePrefix, RoutePrefix2 };

package/dist/chunk-3eecdh6d.js

@@ -0,0 +1,160 @@
+// @bun
+import {
+  normalizePrefix
+} from "./chunk-1jt27yka.js";
+
+// src/ws/marker.ts
+var HANDLER = Symbol.for("dunx.ws.handler");
+var GATEWAY = Symbol.for("dunx.ws.gateway");
+var HandlerKind = Object.freeze({
+  UPGRADE: "upgrade",
+  OPEN: "open",
+  MESSAGE: "message",
+  CLOSE: "close",
+  DRAIN: "drain",
+  PING: "ping",
+  PONG: "pong"
+});
+var markHandler = (target, meta) => {
+  Object.defineProperty(target, HANDLER, { value: meta, configurable: true });
+};
+var handlerMetaOf = (value) => typeof value === "function" ? value[HANDLER] : undefined;
+var markGateway = (target, path) => {
+  Object.defineProperty(target, GATEWAY, { value: path, configurable: true });
+};
+var gatewayPathOf = (target) => target[GATEWAY] ?? "/";
+var isGateway2 = (target) => target[GATEWAY] !== undefined;
+
+// src/server/context.ts
+var EMPTY = new Map;
+var buildContext2 = (route) => {
+  const record = route.meta ?? EMPTY;
+  return Object.freeze({
+    controller: route.controller,
+    handler: route.handlerName,
+    method: route.method,
+    path: route.path,
+    parsesBody: route.options?.body !== undefined,
+    get: (key) => record.get(key.id)
+  });
+};
+
+// src/static/options.ts
+class StaticOptions2 {
+  root;
+  path;
+  maxAge;
+  immutable;
+  constructor(init) {
+    this.root = init.root;
+    this.path = normalizePrefix(init.path ?? "/");
+    this.maxAge = init.maxAge ?? 60;
+    this.immutable = init.immutable ?? (() => false);
+  }
+}
+Object.defineProperty(StaticOptions2, Symbol.for("dunx.deps"), { value: () => [{ unresolved: "init: StaticOptionsInit" }] });
+
+// src/static/files.ts
+import { join, normalize, resolve } from "path";
+var IMMUTABLE_CACHE_CONTROL2 = "public, max-age=31536000, immutable";
+
+class StaticFiles2 {
+  #options;
+  #root;
+  #prefix;
+  constructor(options) {
+    this.#options = options;
+    this.#root = resolve(options.root);
+    this.#prefix = options.path === "/" ? "/" : `${options.path}/`;
+  }
+  resolvePath(pathname) {
+    const relative = pathname.startsWith(this.#prefix) ? pathname.slice(this.#prefix.length) : pathname.slice(this.#options.path.length);
+    let decoded;
+    try {
+      decoded = decodeURIComponent(relative);
+    } catch {
+      return;
+    }
+    if (decoded.includes("\x00"))
+      return;
+    const candidate = resolve(join(this.#root, normalize(decoded)));
+    if (candidate !== this.#root && !candidate.startsWith(`${this.#root}/`)) {
+      return;
+    }
+    return candidate;
+  }
+  #cacheControl(pathname) {
+    const { immutable, maxAge } = this.#options;
+    return immutable(pathname) ? IMMUTABLE_CACHE_CONTROL2 : `public, max-age=${maxAge}`;
+  }
+  async handle(req, _ctx, next) {
+    const { pathname } = new URL(req.url);
+    if (pathname !== this.#options.path && !pathname.startsWith(this.#prefix)) {
+      return next();
+    }
+    if (req.method !== "GET" && req.method !== "HEAD")
+      return next();
+    const path = this.resolvePath(pathname);
+    if (path === undefined)
+      return next();
+    const file = Bun.file(path);
+    if (!await file.exists())
+      return next();
+    return new Response(file, {
+      headers: {
+        "cache-control": this.#cacheControl(pathname),
+        ...file.type === "" ? { "content-type": "application/octet-stream" } : {},
+        "x-content-type-options": "nosniff"
+      }
+    });
+  }
+}
+Object.defineProperty(StaticFiles2, Symbol.for("dunx.deps"), { value: () => [StaticOptions2] });
+
+// src/ws/discover.ts
+import {
+  AppError,
+  classOf,
+  markedMethods
+} from "@dunx/core";
+var normalizePath = (path) => {
+  const joined = `/${path}`.replace(/\/{2,}/g, "/");
+  return joined.length > 1 ? joined.replace(/\/$/, "") : "/";
+};
+var eachHandler = (start) => markedMethods(start, handlerMetaOf);
+var discoverGateway = (instance) => {
+  const klass = instance.constructor;
+  const members = instance;
+  return {
+    name: klass.name,
+    path: normalizePath(gatewayPathOf(klass)),
+    handlers: eachHandler(Object.getPrototypeOf(instance)).map(({ name, meta }) => ({
+      kind: meta.kind,
+      event: meta.event,
+      method: name,
+      invoke: members[name].bind(instance)
+    }))
+  };
+};
+var findHandlerMethod = (ctor) => eachHandler(ctor.prototype)[0]?.name;
+var discoverGateways = (modules, resolve) => {
+  const discovered = [];
+  for (const module of modules) {
+    for (const entry of module.options.providers ?? []) {
+      const candidate = classOf(entry);
+      if (!candidate)
+        continue;
+      if (isGateway2(candidate.ctor)) {
+        discovered.push(discoverGateway(resolve(candidate.token)));
+        continue;
+      }
+      const orphan = findHandlerMethod(candidate.ctor);
+      if (orphan !== undefined) {
+        throw new AppError(`${candidate.ctor.name}.${orphan}() is a websocket handler, but ` + `${candidate.ctor.name} is not a gateway. Decorate the class with ` + "@Gateway(path), or drop the handler decorator.");
+      }
+    }
+  }
+  return discovered;
+};
+
+export { HandlerKind, markHandler, markGateway, isGateway2, discoverGateway, discoverGateways, buildContext2, StaticOptions2, IMMUTABLE_CACHE_CONTROL2, StaticFiles2 };

package/dist/client/json.d.ts

@@ -8,17 +8,7 @@
  * the caller and should say so.
  */
 export declare const safeStringify: (value: unknown) => string;
-/**
- * A plain object: `{}`, `Object.create(null)`, or a JSON-parsed value. Anything
- * with its own prototype - `Date`, `Map`, `Error`, a class instance - is not one.
- *
- * The prototype check rather than the reference's `typeof === 'object' && !Array
- * && !(instanceof Error)`, which answered `true` for a `Date` and for every class
- * instance, so "is this a plain object" did not mean what it said. Body routing
- * does not use this - see {@link isJsonBody} - so tightening it changes no
- * behaviour beyond making the predicate honest.
- */
-export declare const isPlainObject: (value: unknown) => value is Record<string, unknown>;
+export { isPlainObject } from '@dunx/core';
 /**
  * Whether a payload should be JSON-encoded, or handed to `fetch` as-is.
  *
@@ -32,3 +22,14 @@ export declare const isPlainObject: (value: unknown) => value is Record<string,
  * JSON-encodable; a `Blob` is neither.
  */
 export declare const isJsonBody: (payload: unknown) => boolean;
+/**
+ * JSON when the upstream said so or the body parses; text otherwise; undefined
+ * for empty.
+ *
+ * **A failed read rejects.** It used to be caught and reported as an empty body,
+ * so a 2xx whose body died mid-stream reached the caller as a success with no
+ * data, and a retry policy saw nothing to retry. A caller that wants the old
+ * behaviour asks for it: the two error paths in `HttpService` do, because there
+ * the status is the signal and an unreadable body should not replace it.
+ */
+export declare const readBody: (response: Response) => Promise<unknown>;

package/dist/client/options.d.ts

@@ -1,4 +1,4 @@
-import type { RetryOptions } from './retry.js';
+import type { HttpRetryOptions } from './retry.js';
 /**
  * Named `HttpClientOptions`, not `HttpOptions`: the server half already exports
  * that from `@dunx/http` for `HttpFactory.create`, and two things called
@@ -15,7 +15,7 @@ export interface HttpClientOptionsInit {
     readonly timeoutMs?: number;
     /** Sent on every request, under anything a call sets itself. */
     readonly headers?: Readonly<Record<string, string>>;
-    readonly retry?: RetryOptions<unknown>;
+    readonly retry?: HttpRetryOptions;
     /**
      * Forward W3C Trace Context upstream as `traceparent`, so the callee's spans
      * join this request's trace and one trace spans both services.
@@ -71,7 +71,7 @@ export declare class HttpClientOptions {
     readonly baseUrl: string | undefined;
     readonly timeoutMs: number;
     readonly headers: Readonly<Record<string, string>>;
-    readonly retry: RetryOptions<unknown>;
+    readonly retry: HttpRetryOptions;
     readonly propagateTrace: boolean;
     readonly name: string | undefined;
     readonly fetchOptions: Readonly<Record<string, unknown>>;

package/dist/client/retry.d.ts

@@ -1,49 +1,35 @@
-export interface BackoffOptions {
-    /** Base delay, doubled each attempt. */
-    readonly baseMs: number;
-    /** @default 2 */
-    readonly power?: number;
-    /** Upper bound of the random component added to each delay. @default 1000 */
-    readonly jitterMs?: number;
-    /** @default 30000 */
-    readonly maxMs?: number;
-}
-/** `base * power^attempt + jitter`, capped. `attempt` is 0 for the first retry. */
-export declare const backoffDelay: (attempt: number, { baseMs, power, jitterMs, maxMs }: BackoffOptions) => number;
+import { RetryClassifier, type RetryOptions, type RetryVerdict } from '@dunx/core';
 /**
  * The wait an upstream asked for, in ms, or undefined.
  *
  * RFC 9110 allows either a delay in seconds or an HTTP date, and both appear in
- * the wild - GitHub sends seconds, some CDNs send a date. Ignoring the header, as
- * the reference did, means retrying straight back into a rate limit that had just
- * told you exactly how long to wait.
+ * the wild: GitHub sends seconds, some CDNs send a date. Ignoring the header means
+ * retrying straight back into a rate limit that had just said how long to wait.
  */
 export declare const retryAfterMs: (headers: Headers, now?: number) => number | undefined;
 /**
  * Statuses worth trying again: a server that failed, one that is overloaded, and
- * one that timed out. Deliberately narrower than the source, which also retried
- * 409 and 422 - both of those are the server rejecting the *request*, and sending
- * it again unchanged gets the same answer.
+ * one that timed out. Narrower than 409 and 422, which are the server rejecting
+ * the *request* - sending it again unchanged gets the same answer.
  */
 export declare const isRetryableStatus: (status: number) => boolean;
-export interface RetryOptions<T> {
-    /** Retries *after* the first attempt, so 3 means up to 4 calls. @default 3 */
-    readonly maxRetries?: number;
-    /** @default 1000 */
-    readonly retryDelayMs?: number;
-    readonly backoff?: Omit<BackoffOptions, 'baseMs'>;
+/** Core's generic retry knobs plus the two an HTTP failure carries. */
+export interface HttpRetryOptions<T = unknown> extends RetryOptions<T> {
     /** @default isRetryableStatus */
     readonly shouldRetryOnStatus?: (status: number) => boolean;
     /** Honour a `Retry-After` header over the computed backoff. @default true */
     readonly respectRetryAfter?: boolean;
-    readonly onAttempt?: (attempt: number, isRetry: boolean) => void;
-    readonly onError?: (error: unknown, attempt: number, willRetry: boolean) => void;
-    readonly onSuccess?: (result: T, attempt: number) => void;
 }
 /**
- * Runs `operation`, retrying per `options`.
+ * The HTTP half of the retry decision, and the only place in dunx's resilience
+ * path that knows what a status is.
  *
- * `Bun.sleep` rather than a `setTimeout` promise: it is the runtime's own timer and
- * needs no wrapper.
+ * An abort is never retried: the caller's signal fired or the timeout expired, and
+ * both mean the budget for this call is spent. A transport failure is retried,
+ * because a refused connection is the case retrying exists for.
  */
-export declare const executeWithRetry: <T>(operation: () => Promise<T> | T, options?: RetryOptions<T>) => Promise<T>;
+export declare class HttpRetryClassifier extends RetryClassifier {
+    private readonly options;
+    constructor(options?: HttpRetryOptions);
+    classify(error: unknown): RetryVerdict;
+}

package/dist/client/service.d.ts

@@ -1,8 +1,9 @@
 import { Logger, RequestContext } from '@dunx/core';
 import { UrlHelper, type ParamsType } from '@arkv/shared';
 import type { HttpMethod } from '../route/marker.js';
+import { type SseMessage } from './sse.js';
 import { HttpClientOptions } from './options.js';
-import { type RetryOptions } from './retry.js';
+import { type HttpRetryOptions } from './retry.js';
 /** The client speaks two more verbs than a route can declare. */
 export type RequestMethod = HttpMethod | 'HEAD' | 'OPTIONS';
 /**
@@ -36,11 +37,15 @@ export interface RequestConfig<TRequest = unknown, TResponse = unknown> {
     readonly headerFactory?: HeaderFactory;
     /** Merged into the async context for this call, so its logs carry it. */
     readonly flow?: string;
-    readonly retry?: RetryOptions<TResponse>;
+    readonly retry?: HttpRetryOptions<TResponse>;
     /** Cancels the call. Combined with the timeout, whichever fires first. */
     readonly signal?: AbortSignal;
 }
 type BaseOptions<TRequest, TResponse> = Omit<RequestConfig<TRequest, TResponse>, 'method' | 'url' | 'payload'>;
+/** What both SSE readers take: no retry, and only the verbs a stream uses. */
+type SseConfig<TRequest> = Omit<RequestConfig<TRequest>, 'method' | 'retry'> & {
+    readonly method?: 'GET' | 'POST';
+};
 /**
  * A `fetch` client with a per-request timeout, retry with backoff, W3C Trace
  * Context propagation and one log line per call. `fetch` and nothing else, so there is no
@@ -61,21 +66,19 @@ export declare class HttpService extends UrlHelper {
     put<TRequest = unknown, TResponse = unknown>(url?: string | URL, payload?: TRequest, options?: BaseOptions<TRequest, TResponse>): Promise<TResponse>;
     patch<TRequest = unknown, TResponse = unknown>(url?: string | URL, payload?: TRequest, options?: BaseOptions<TRequest, TResponse>): Promise<TResponse>;
     delete<TResponse = unknown>(url?: string | URL, options?: BaseOptions<never, TResponse>): Promise<TResponse>;
+    /** Each `data:` payload of an event stream, `[DONE]` consumed rather than
+     * yielded. {@link streamSseEvents} keeps the envelope too. */
+    streamSse<TRequest = unknown>(config: SseConfig<TRequest>): AsyncGenerator<string>;
     /**
-     * Yields each `data:` payload of a Server-Sent-Events response, consuming the
-     * terminating `[DONE]` sentinel rather than yielding it.
+     * The same response, each event whole: the joined `data` plus whatever `event`,
+     * `id` and `retry` it carried. `id` is what a reconnect sends as `Last-Event-ID`.
      *
      * **No retry**, deliberately: a partially consumed stream cannot be replayed, so
      * retrying would re-deliver events the caller has already seen. The timeout
-     * covers the connect only - it is dropped once headers arrive, or a long-lived
-     * stream would be cut off mid-flight.
-     *
-     * Hand-rolled rather than delegated: Bun exposes no `EventSource` global and no
-     * SSE parser, which was measured rather than assumed.
+     * covers the connect only - dropped once headers arrive, or a long-lived stream
+     * would be cut off mid-flight.
      */
-    streamSse<TRequest = unknown>(config: Omit<RequestConfig<TRequest>, 'method' | 'retry'> & {
-        readonly method?: 'GET' | 'POST';
-    }): AsyncGenerator<string>;
+    streamSseEvents<TRequest = unknown>(config: SseConfig<TRequest>): AsyncGenerator<SseMessage>;
     /**
      * Resolves the target: an absolute url, a path relative to `baseUrl`, or
      * `baseUrl` plus an explicit `path`.
@@ -86,6 +89,12 @@ export declare class HttpService extends UrlHelper {
      * regex, so it cannot disagree with `new URL`.
      */
     private urlFor;
+    /**
+     * One policy per call, because the budget and the caller's signal are. Core owns
+     * the timeout, the loop and the backoff; `HttpRetryClassifier` is the only part
+     * of it that knows what a status is.
+     */
+    private policyFor;
     /** `serialised` is what a `headerFactory` signs, and is `''` for no body. */
     private bodyFor;
     private send;

package/dist/client/sse.d.ts

@@ -0,0 +1,39 @@
+/** One dispatched event as it arrived. Not `SseEvent`, the write side, where
+ * `data` is any value rather than the text off the wire. */
+export interface SseMessage {
+    /** The `data:` lines of one event, joined with `\n` as the spec requires. */
+    readonly data: string;
+    /** The `event:` name, absent for the default `message`. */
+    readonly event?: string;
+    readonly id?: string;
+    /** The reconnection delay the server asked for, in milliseconds. */
+    readonly retry?: number;
+}
+/**
+ * Every event of a server-sent-events body, in order, ending with the stream or
+ * with `[DONE]`. One still being read when the body ends is dropped, per spec.
+ *
+ * Async iteration rather than `getReader()`, which releases the reader on
+ * completion, on a consumer `break` and on the `[DONE]` return. Hand-rolled:
+ * Bun exposes no `EventSource` global and no SSE parser, measured not assumed.
+ */
+export declare function sseMessages(body: ReadableStream<Uint8Array>): AsyncGenerator<SseMessage>;
+/**
+ * The `data:` payloads alone, one string per event rather than per line, so a
+ * multi-line payload arrives as it was sent.
+ */
+export declare function sseData(body: ReadableStream<Uint8Array>): AsyncGenerator<string>;
+/**
+ * A deadline on the connect alone.
+ *
+ * An `AbortSignal.timeout` handed to `fetch` keeps aborting after the headers
+ * arrive, which cut a 600 ms stream at 200 ms when the policy supplied one. This
+ * holds its timer so the caller can drop it the moment `fetch` resolves, leaving
+ * the body cancellable only by the caller's own signal.
+ */
+export declare class ConnectDeadline {
+    #private;
+    constructor(ms: number, target: string);
+    get signal(): AbortSignal;
+    clear(): void;
+}

package/dist/client.d.ts

@@ -7,6 +7,15 @@
  */
 export { FetchError, FetchTransportError } from './client/errors.js';
 export { HttpClientOptions, type HttpClientOptionsInit, } from './client/options.js';
-export type { BackoffOptions, RetryOptions } from './client/retry.js';
+/**
+ * Retry, backoff and jitter are `@dunx/core`'s, re-exported so an import of this
+ * subpath still names them. What stays here is the HTTP half of the decision:
+ * `HttpRetryClassifier` reads a status and a `Retry-After`, which is the seam that
+ * keeps both out of core.
+ */
+export type { BackoffOptions, RetryOptions } from '@dunx/core';
+export { HttpRetryClassifier, type HttpRetryOptions } from './client/retry.js';
 export { httpClient, HttpModule, type ClientTarget } from './client/module.js';
 export { HttpService, type HeaderFactory, type RequestConfig, type RequestMethod, } from './client/service.js';
+/** What `streamSseEvents` yields: one dispatched event, envelope included. */
+export type { SseMessage } from './client/sse.js';