@webpieces/http-client-browser 0.4.868 → 0.4.869

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/http-client-browser",
-  "version": "0.4.868",
+  "version": "0.4.869",
   "description": "Browser HTTP client for webpieces: DI-free (React or Angular), app-managed context store, no AsyncLocalStorage",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -22,7 +22,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@webpieces/core-util": "0.4.868",
-    "@webpieces/http-client-core": "0.4.868"
+    "@webpieces/core-util": "0.4.869",
+    "@webpieces/http-client-core": "0.4.869"
   }
 }

package/src/RequestLifecycleListener.d.ts

@@ -18,23 +18,31 @@ import { RequestOutcome } from '@webpieces/http-client-core';
  * `onRequestStart` and `onRequestEnd` are PAIRED: every start is followed by exactly one end, on
  * every path (2xx, HTTP error, network reject), so a counter driven off them cannot leak.
  *
- * `route.background` is the endpoint's own declaration that it is plumbing the user did not ask for
- * — a log shipper, a heartbeat, a telemetry flush (`@Endpoint(..., { background: true })`). It is not
- * progress, so a bar driven off these callbacks should skip it, and so should any app-level RPC
- * instrumentation whose own lines would otherwise become the next batch's payload. webpieces already
- * emits no `[API-client-*]` line for such a route; this is the app's half of the same fact, read from
- * the ROUTE rather than matched on a path string.
+ * Three independent endpoint declarations ride the route, each read from the ROUTE rather than
+ * matched on a path string, each false when absent:
+ *
+ * - `route.hideProgress` (`@Endpoint(..., { hideProgress: true })`) — the user is not waiting on this
+ *   call (a background download, a log shipper), so a bar driven off these callbacks should skip it.
+ * - `route.allowUpgradeInFlight` (`@Endpoint(..., { allowUpgradeInFlight: true })`) — the app may
+ *   upgrade while this call is in flight, and the call neither blocks nor arms that upgrade. Absent,
+ *   the call must finish before an upgrade, and its success counts toward arming one — even when it
+ *   is hidden from the bar.
+ * - `route.noLogging` (`@Endpoint(..., { noLogging: true })`) — webpieces already emits no
+ *   `[API-client-*]` line for it; app-level RPC instrumentation whose own lines would become the next
+ *   log batch's payload should skip it too.
+ *
+ * A log shipper declares all three; a background download declares only `hideProgress`.
  *
  * ```typescript
  * class RpcLifecycleListener implements RequestLifecycleListener {
  *     onRequestStart(route: RouteMetadata): void {
- *         if (route.background) return;
- *         progressBar.noteRequestStart();
+ *         if (!route.allowUpgradeInFlight) upgradeGate.noteRequestStart();
+ *         if (!route.hideProgress) progressBar.noteRequestStart();
  *     }
  *     onRequestEnd(route: RouteMetadata, outcome: RequestOutcome): void {
  *         serverVersionBridge.set(outcome.headers?.get('x-myorg-server-version'));
- *         if (route.background) return;
- *         progressBar.noteRequestEnd(!outcome.ok);
+ *         if (!route.allowUpgradeInFlight) upgradeGate.noteRequestEnd(outcome.ok);
+ *         if (!route.hideProgress) progressBar.noteRequestEnd(!outcome.ok);
  *     }
  * }
  * const factory = new ClientHttpBrowserFactory(store, new RpcLifecycleListener());

package/src/RequestLifecycleListener.js.map

@@ -1 +1 @@
-{"version":3,"file":"RequestLifecycleListener.js","sourceRoot":"","sources":["../../../../../packages/http/http-client-browser/src/RequestLifecycleListener.ts"],"names":[],"mappings":"","sourcesContent":["import { RouteMetadata } from '@webpieces/core-util';\nimport { RequestOutcome } from '@webpieces/http-client-core';\n\n/**\n * The inbound seam an app implements to observe the FULL lifecycle of every RPC call — symmetric\n * with the outbound header propagation done by {@link MutableContextStore} / {@link ContextMgr}.\n * Registered once on {@link ClientHttpBrowserFactory}; invoked by {@link BrowserProxyClient} around\n * each call.\n *\n * Replaces the older header-only ResponseHeadersListener. `onRequestEnd`'s `outcome.headers` carries\n * the same Response Headers (after settlement, on both ok and error), and it adds the\n * two signals the header-only seam could not give: a START marker, and success-or-error.\n *\n * The driver is a browser app that must drive ONE progress bar across N requests per user action,\n * AND detect that a newer server is deployed than this bundle (the server stamps\n * `x-<org>-server-version` on every response) — reloading only at a safe moment, so a half-filled\n * form is never blown away. It needs, per RPC: bar on, bar off, the outcome, and the headers.\n *\n * `onRequestStart` and `onRequestEnd` are PAIRED: every start is followed by exactly one end, on\n * every path (2xx, HTTP error, network reject), so a counter driven off them cannot leak.\n *\n * `route.background` is the endpoint's own declaration that it is plumbing the user did not ask for\n * — a log shipper, a heartbeat, a telemetry flush (`@Endpoint(..., { background: true })`). It is not\n * progress, so a bar driven off these callbacks should skip it, and so should any app-level RPC\n * instrumentation whose own lines would otherwise become the next batch's payload. webpieces already\n * emits no `[API-client-*]` line for such a route; this is the app's half of the same fact, read from\n * the ROUTE rather than matched on a path string.\n *\n * ```typescript\n * class RpcLifecycleListener implements RequestLifecycleListener {\n *     onRequestStart(route: RouteMetadata): void {\n *         if (route.background) return;\n *         progressBar.noteRequestStart();\n *     }\n *     onRequestEnd(route: RouteMetadata, outcome: RequestOutcome): void {\n *         serverVersionBridge.set(outcome.headers?.get('x-myorg-server-version'));\n *         if (route.background) return;\n *         progressBar.noteRequestEnd(!outcome.ok);\n *     }\n * }\n * const factory = new ClientHttpBrowserFactory(store, new RpcLifecycleListener());\n * ```\n *\n * This is BUSINESS LOGIC (methods), so it is an interface, not a data class — unlike the\n * {@link RequestOutcome} it is handed.\n */\nexport interface RequestLifecycleListener {\n    /** Before fetch, once per RPC. */\n    onRequestStart(route: RouteMetadata): void;\n\n    /** Once, after the call settles, on every path (success, HTTP error, network reject). */\n    onRequestEnd(route: RouteMetadata, outcome: RequestOutcome): void;\n}\n"]}
+{"version":3,"file":"RequestLifecycleListener.js","sourceRoot":"","sources":["../../../../../packages/http/http-client-browser/src/RequestLifecycleListener.ts"],"names":[],"mappings":"","sourcesContent":["import { RouteMetadata } from '@webpieces/core-util';\nimport { RequestOutcome } from '@webpieces/http-client-core';\n\n/**\n * The inbound seam an app implements to observe the FULL lifecycle of every RPC call — symmetric\n * with the outbound header propagation done by {@link MutableContextStore} / {@link ContextMgr}.\n * Registered once on {@link ClientHttpBrowserFactory}; invoked by {@link BrowserProxyClient} around\n * each call.\n *\n * Replaces the older header-only ResponseHeadersListener. `onRequestEnd`'s `outcome.headers` carries\n * the same Response Headers (after settlement, on both ok and error), and it adds the\n * two signals the header-only seam could not give: a START marker, and success-or-error.\n *\n * The driver is a browser app that must drive ONE progress bar across N requests per user action,\n * AND detect that a newer server is deployed than this bundle (the server stamps\n * `x-<org>-server-version` on every response) — reloading only at a safe moment, so a half-filled\n * form is never blown away. It needs, per RPC: bar on, bar off, the outcome, and the headers.\n *\n * `onRequestStart` and `onRequestEnd` are PAIRED: every start is followed by exactly one end, on\n * every path (2xx, HTTP error, network reject), so a counter driven off them cannot leak.\n *\n * Three independent endpoint declarations ride the route, each read from the ROUTE rather than\n * matched on a path string, each false when absent:\n *\n * - `route.hideProgress` (`@Endpoint(..., { hideProgress: true })`) — the user is not waiting on this\n *   call (a background download, a log shipper), so a bar driven off these callbacks should skip it.\n * - `route.allowUpgradeInFlight` (`@Endpoint(..., { allowUpgradeInFlight: true })`) — the app may\n *   upgrade while this call is in flight, and the call neither blocks nor arms that upgrade. Absent,\n *   the call must finish before an upgrade, and its success counts toward arming one — even when it\n *   is hidden from the bar.\n * - `route.noLogging` (`@Endpoint(..., { noLogging: true })`) — webpieces already emits no\n *   `[API-client-*]` line for it; app-level RPC instrumentation whose own lines would become the next\n *   log batch's payload should skip it too.\n *\n * A log shipper declares all three; a background download declares only `hideProgress`.\n *\n * ```typescript\n * class RpcLifecycleListener implements RequestLifecycleListener {\n *     onRequestStart(route: RouteMetadata): void {\n *         if (!route.allowUpgradeInFlight) upgradeGate.noteRequestStart();\n *         if (!route.hideProgress) progressBar.noteRequestStart();\n *     }\n *     onRequestEnd(route: RouteMetadata, outcome: RequestOutcome): void {\n *         serverVersionBridge.set(outcome.headers?.get('x-myorg-server-version'));\n *         if (!route.allowUpgradeInFlight) upgradeGate.noteRequestEnd(outcome.ok);\n *         if (!route.hideProgress) progressBar.noteRequestEnd(!outcome.ok);\n *     }\n * }\n * const factory = new ClientHttpBrowserFactory(store, new RpcLifecycleListener());\n * ```\n *\n * This is BUSINESS LOGIC (methods), so it is an interface, not a data class — unlike the\n * {@link RequestOutcome} it is handed.\n */\nexport interface RequestLifecycleListener {\n    /** Before fetch, once per RPC. */\n    onRequestStart(route: RouteMetadata): void;\n\n    /** Once, after the call settles, on every path (success, HTTP error, network reject). */\n    onRequestEnd(route: RouteMetadata, outcome: RequestOutcome): void;\n}\n"]}