@absolutejs/absolute 0.19.0-beta.350 → 0.19.0-beta.351

package/dist/src/core/responseEnhancers.d.ts

@@ -1,9 +1,10 @@
-import { type AppendStreamingSlotsOptions, type StreamingSlot } from '../utils/streamingSlots';
+import { type AppendStreamingSlotsOptions, type StreamingSlotPolicy, type StreamingSlot } from '../utils/streamingSlots';
 type ResponseLike = Response | Promise<Response>;
 export type StreamingSlotEnhancerOptions = Omit<AppendStreamingSlotsOptions, 'injectRuntime'> & {
     streamingSlots?: StreamingSlot[];
+    policy?: StreamingSlotPolicy;
 };
-export declare const enhanceHtmlResponseWithStreamingSlots: (response: Response, { nonce, onError, streamingSlots }?: StreamingSlotEnhancerOptions) => Response;
+export declare const enhanceHtmlResponseWithStreamingSlots: (response: Response, { nonce, onError, streamingSlots, policy }?: StreamingSlotEnhancerOptions) => Response;
 export declare const withStreamingSlots: (responseLike: ResponseLike, options?: StreamingSlotEnhancerOptions) => Promise<Response>;
 export declare const withRegisteredStreamingSlots: (renderResponse: () => ResponseLike, options?: StreamingSlotEnhancerOptions) => Promise<Response>;
 export {};

package/dist/src/utils/index.d.ts

@@ -5,4 +5,5 @@ export * from './defineEnv';
 export * from './getEnv';
 export * from './networking';
 export * from './registerClientScript';
+export * from './streamingSlotMetricSink';
 export * from './streamingSlots';

package/dist/src/utils/streamingSlotMetricSink.d.ts

@@ -0,0 +1,18 @@
+import type { StreamingSlotMetric, StreamingSlotMetricHandler, StreamingSlotMetricType } from './streamingSlots';
+export type StreamingSlotMetricMetadataValue = string | number | boolean | null;
+export type StreamingSlotMetricMetadata = Record<string, StreamingSlotMetricMetadataValue>;
+export type StreamingSlotMetricSinkEvent = StreamingSlotMetric & {
+    at: number;
+    route?: string;
+    metadata?: StreamingSlotMetricMetadata;
+};
+export type StreamingSlotMetricSinkOptions = {
+    onReport?: (metric: StreamingSlotMetricSinkEvent) => void | Promise<void>;
+    onError?: (error: unknown, metric: StreamingSlotMetricSinkEvent) => void;
+    route?: string;
+    metadata?: StreamingSlotMetricMetadata;
+    includeTypes?: StreamingSlotMetricType[];
+    excludeTypes?: StreamingSlotMetricType[];
+    sampleRate?: number;
+};
+export declare const createStreamingSlotMetricSink: ({ excludeTypes, includeTypes, metadata, onReport, onError, route, sampleRate }?: StreamingSlotMetricSinkOptions) => StreamingSlotMetricHandler;

package/dist/src/utils/streamingSlots.d.ts

@@ -1,4 +1,33 @@
 type SlotResolver = () => Promise<string> | string;
+type SlotErrorHandler = (error: unknown, slot: StreamingSlot) => void;
+export type StreamingSlotMetricType = 'prepared' | 'dropped' | 'resolved' | 'patched' | 'timeout' | 'size_exceeded' | 'error';
+export type StreamingSlotMetric = {
+    type: StreamingSlotMetricType;
+    slotId: string;
+    durationMs?: number;
+    bytes?: number;
+    reason?: string;
+    error?: unknown;
+};
+export type StreamingSlotMetricHandler = (metric: StreamingSlotMetric) => void;
+export type StreamingSlotPolicy = {
+    timeoutMs?: number;
+    fallbackHtml?: string;
+    errorHtml?: string;
+    maxSlotsPerResponse?: number;
+    maxSlotHtmlSizeBytes?: number;
+    onError?: SlotErrorHandler;
+    onSlotMetric?: StreamingSlotMetricHandler;
+};
+type StreamingSlotPolicyValue = {
+    timeoutMs: number;
+    fallbackHtml: string;
+    errorHtml?: string;
+    maxSlotsPerResponse: number;
+    maxSlotHtmlSizeBytes: number;
+    onError?: SlotErrorHandler;
+    onSlotMetric?: StreamingSlotMetricHandler;
+};
 export type StreamingSlot = {
     errorHtml?: string;
     fallbackHtml?: string;
@@ -12,12 +41,16 @@ type DeferredStreamingSlot = Omit<StreamingSlot, 'id'> & {
 export type AppendStreamingSlotsOptions = {
     injectRuntime?: boolean;
     nonce?: string;
+    policy?: StreamingSlotPolicy;
+    onSlotMetric?: StreamingSlotMetricHandler;
     onError?: (error: unknown, slot: StreamingSlot) => void;
 };
 export type StreamOutOfOrderSlotsOptions = {
     footerHtml?: string;
     headerHtml?: string;
     nonce?: string;
+    policy?: StreamingSlotPolicy;
+    onSlotMetric?: StreamingSlotMetricHandler;
     onError?: (error: unknown, slot: StreamingSlot) => void;
     slots: DeferredStreamingSlot[];
 };
@@ -27,7 +60,10 @@ export declare const renderStreamingSlotsRuntimeTag: (nonce?: string) => string;
 export declare const renderStreamingSlotPlaceholder: (id: string, fallbackHtml?: string) => string;
 export declare const renderStreamingSlotPatchTag: (id: string, html: string, nonce?: string) => string;
 export declare const injectHtmlIntoHead: (html: string, injection: string) => string;
-export declare const streamOutOfOrderSlots: ({ footerHtml, headerHtml, nonce, onError, slots }: StreamOutOfOrderSlotsOptions) => ReadableStream<Uint8Array<ArrayBufferLike>>;
+export declare const getStreamingSlotPolicy: () => StreamingSlotPolicyValue;
+export declare const setStreamingSlotPolicy: (policy?: StreamingSlotPolicy) => void;
+export declare const withStreamingSlotPolicy: <T>(policy: StreamingSlotPolicy, callback: () => Promise<T> | T) => Promise<T>;
+export declare const streamOutOfOrderSlots: ({ footerHtml, headerHtml, nonce, policy, onSlotMetric, onError, slots }: StreamOutOfOrderSlotsOptions) => ReadableStream<Uint8Array<ArrayBufferLike>>;
 export declare const injectStreamingRuntimeIntoStream: (stream: ReadableStream<string | Uint8Array>, nonce?: string) => ReadableStream<Uint8Array<ArrayBufferLike>>;
-export declare const appendStreamingSlotPatchesToStream: (stream: ReadableStream<string | Uint8Array>, slots?: StreamingSlot[], { injectRuntime, nonce, onError }?: AppendStreamingSlotsOptions) => ReadableStream<Uint8Array<ArrayBufferLike>>;
+export declare const appendStreamingSlotPatchesToStream: (stream: ReadableStream<string | Uint8Array>, slots?: DeferredStreamingSlot[], { injectRuntime, nonce, onError, onSlotMetric, policy }?: AppendStreamingSlotsOptions) => ReadableStream<string | Uint8Array<ArrayBufferLike>>;
 export {};

package/dist/svelte/index.js

@@ -30881,6 +30881,9 @@ var CLOSING_PAGE_TAG_REGEX = /<\/body>\s*<\/html>\s*$/i;
 var STREAMING_RUNTIME_GLOBAL = "__ABS_SLOT_ENQUEUE__";
 var STREAMING_PENDING_GLOBAL = "__ABS_SLOT_PENDING__";
 var STREAM_TAIL_LOOKBEHIND = 128;
+var STREAMING_SLOT_TIMEOUT_MS = 5000;
+var STREAMING_SLOT_MAX_PER_RESPONSE = 128;
+var STREAMING_SLOT_MAX_HTML_BYTES = 64000;
 var createSlotPlaceholderId = (id) => `${SLOT_PLACEHOLDER_PREFIX}${id}`;
 var createSlotPatchStatement = (id, html) => `(window.${STREAMING_RUNTIME_GLOBAL}||function(i,h){window.${STREAMING_PENDING_GLOBAL}=window.${STREAMING_PENDING_GLOBAL}||{};window.${STREAMING_PENDING_GLOBAL}[i]=h;})(${JSON.stringify(id)},${JSON.stringify(html)});`;
 var createNonceAttr = (nonce) => nonce ? ` nonce="${nonce}"` : "";
@@ -30897,32 +30900,197 @@ var injectHtmlIntoHead = (html, injection) => {
   return `${html}${injection}`;
 };
 var toUint8 = (value, encoder) => encoder.encode(value);
-var toStreamingSlot = (slot) => ({
-  ...slot,
-  id: slot.id ?? createStreamingSlotId()
+var currentStreamingSlotPolicy = {
+  timeoutMs: STREAMING_SLOT_TIMEOUT_MS,
+  fallbackHtml: "",
+  errorHtml: undefined,
+  maxSlotsPerResponse: STREAMING_SLOT_MAX_PER_RESPONSE,
+  maxSlotHtmlSizeBytes: STREAMING_SLOT_MAX_HTML_BYTES
+};
+var clonePolicy = (policy) => ({
+  ...policy
+});
+var normalizeSlotBytes = (value, fallback) => {
+  if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
+    return Math.floor(value);
+  }
+  return fallback;
+};
+var normalizeSlotText = (value, fallback) => typeof value === "string" ? value : fallback;
+var normalizeSlotError = (value, fallback) => typeof value === "string" ? value : fallback;
+var hasPolicyValue = (policy, key) => Object.prototype.hasOwnProperty.call(policy, key);
+var applyStreamingSlotPolicyOverrides = (base, overridePolicy = {}) => ({
+  timeoutMs: hasPolicyValue(overridePolicy, "timeoutMs") ? normalizeSlotBytes(overridePolicy.timeoutMs, base.timeoutMs) : base.timeoutMs,
+  fallbackHtml: hasPolicyValue(overridePolicy, "fallbackHtml") ? normalizeSlotText(overridePolicy.fallbackHtml, "") : base.fallbackHtml,
+  errorHtml: hasPolicyValue(overridePolicy, "errorHtml") ? normalizeSlotError(overridePolicy.errorHtml) : base.errorHtml,
+  maxSlotsPerResponse: hasPolicyValue(overridePolicy, "maxSlotsPerResponse") ? normalizeSlotBytes(overridePolicy.maxSlotsPerResponse, base.maxSlotsPerResponse) : base.maxSlotsPerResponse,
+  maxSlotHtmlSizeBytes: hasPolicyValue(overridePolicy, "maxSlotHtmlSizeBytes") ? normalizeSlotBytes(overridePolicy.maxSlotHtmlSizeBytes, base.maxSlotHtmlSizeBytes) : base.maxSlotHtmlSizeBytes,
+  onError: hasPolicyValue(overridePolicy, "onError") ? overridePolicy.onError : base.onError,
+  onSlotMetric: hasPolicyValue(overridePolicy, "onSlotMetric") ? overridePolicy.onSlotMetric : base.onSlotMetric
+});
+var createCombinedSlotErrorHandler = (policyOnError, enhancerOnError) => {
+  if (!policyOnError && !enhancerOnError)
+    return;
+  return (error, slot) => {
+    policyOnError?.(error, slot);
+    enhancerOnError?.(error, slot);
+  };
+};
+var createCombinedSlotMetricHandler = (policyOnSlotMetric, callOnSlotMetric) => {
+  if (!policyOnSlotMetric && !callOnSlotMetric)
+    return;
+  return (metric) => {
+    policyOnSlotMetric?.(metric);
+    callOnSlotMetric?.(metric);
+  };
+};
+var resolveStreamingSlotPolicy = (overridePolicy = {}) => {
+  const base = getStreamingSlotPolicy();
+  return applyStreamingSlotPolicyOverrides(base, overridePolicy);
+};
+var getStreamingSlotPolicy = () => clonePolicy(currentStreamingSlotPolicy);
+var setStreamingSlotPolicy = (policy = {}) => {
+  const base = getStreamingSlotPolicy();
+  currentStreamingSlotPolicy = applyStreamingSlotPolicyOverrides(base, policy);
+};
+var withStreamingSlotPolicy = async (policy, callback) => {
+  const previous = getStreamingSlotPolicy();
+  setStreamingSlotPolicy(policy);
+  try {
+    return await callback();
+  } finally {
+    currentStreamingSlotPolicy = previous;
+  }
+};
+var emitSlotMetric = (metric, onSlotMetric) => {
+  onSlotMetric?.(metric);
+};
+var createTimeoutError = (slot, timeoutMs) => {
+  const error = new Error(`Streaming slot "${slot.id}" timed out after ${timeoutMs}ms`);
+  error.__absTimeout = true;
+  return error;
+};
+var toStreamingSlot = (slot, policy) => ({
+  errorHtml: slot.errorHtml === undefined ? policy.errorHtml : slot.errorHtml,
+  fallbackHtml: normalizeSlotText(slot.fallbackHtml, policy.fallbackHtml),
+  id: slot.id ?? createStreamingSlotId(),
+  timeoutMs: normalizeSlotBytes(slot.timeoutMs, policy.timeoutMs),
+  resolve: slot.resolve
 });
-var resolveSlot = async (slot, onError) => {
+var prepareSlots = ({
+  policy,
+  slots,
+  onError,
+  onSlotMetric
+}) => {
+  const preparedSlots = slots.map((slot) => toStreamingSlot(slot, policy));
+  const maxSlotsPerResponse = policy.maxSlotsPerResponse;
+  if (maxSlotsPerResponse === 0) {
+    const error = new Error("Streaming slot limit is set to 0");
+    for (const slot of preparedSlots) {
+      onError?.(error, slot);
+      emitSlotMetric({
+        type: "dropped",
+        slotId: slot.id,
+        reason: "maxSlotsPerResponse is 0"
+      }, onSlotMetric);
+    }
+    return [];
+  }
+  if (preparedSlots.length <= maxSlotsPerResponse) {
+    preparedSlots.forEach((slot) => emitSlotMetric({
+      type: "prepared",
+      slotId: slot.id
+    }, onSlotMetric));
+    return preparedSlots;
+  }
+  const keptSlots = preparedSlots.slice(0, maxSlotsPerResponse);
+  const droppedSlots = preparedSlots.slice(maxSlotsPerResponse);
+  droppedSlots.forEach((slot) => {
+    onError?.(new Error(`Streaming slot "${slot.id}" dropped because ${maxSlotsPerResponse} slots is the configured maximum`), slot);
+    emitSlotMetric({
+      type: "dropped",
+      slotId: slot.id,
+      reason: `maxSlotsPerResponse is ${maxSlotsPerResponse}`
+    }, onSlotMetric);
+  });
+  keptSlots.forEach((slot) => emitSlotMetric({
+    type: "prepared",
+    slotId: slot.id
+  }, onSlotMetric));
+  return keptSlots;
+};
+var htmlByteLength = (value, encoder) => encoder.encode(value).length;
+var resolveSlot = async (slot, onError, policy, onSlotMetric) => {
+  const safePolicy = policy ?? getStreamingSlotPolicy();
+  const encoder = new TextEncoder;
+  const start = Date.now();
   try {
-    const resolved = slot.resolve();
-    const html = typeof slot.timeoutMs === "number" && slot.timeoutMs > 0 ? await Promise.race([
-      Promise.resolve(resolved),
-      new Promise((_, reject) => setTimeout(() => reject(new Error(`Streaming slot "${slot.id}" timed out after ${slot.timeoutMs}ms`)), slot.timeoutMs))
-    ]) : await resolved;
+    const maybeAsyncValue = Promise.resolve(slot.resolve());
+    const resolved = typeof slot.timeoutMs === "number" && slot.timeoutMs > 0 ? await Promise.race([
+      maybeAsyncValue,
+      new Promise((_, reject) => setTimeout(() => {
+        reject(createTimeoutError(slot, slot.timeoutMs ?? 0));
+      }, slot.timeoutMs))
+    ]) : await maybeAsyncValue;
+    const html = typeof resolved === "string" ? resolved : `${resolved}`;
+    if (safePolicy.maxSlotHtmlSizeBytes > 0 && htmlByteLength(html, encoder) > safePolicy.maxSlotHtmlSizeBytes) {
+      const bytes2 = htmlByteLength(html, encoder);
+      const error = new Error(`Streaming slot "${slot.id}" exceeded max payload size of ${safePolicy.maxSlotHtmlSizeBytes} bytes`);
+      const durationMs2 = Date.now() - start;
+      onError?.(error, slot);
+      emitSlotMetric({
+        type: "size_exceeded",
+        slotId: slot.id,
+        durationMs: durationMs2,
+        bytes: bytes2,
+        error
+      }, onSlotMetric);
+      const fallbackHtml = typeof slot.errorHtml === "string" ? slot.errorHtml : null;
+      return {
+        html: fallbackHtml,
+        id: slot.id,
+        durationMs: durationMs2,
+        bytes: fallbackHtml === null ? 0 : htmlByteLength(fallbackHtml, encoder)
+      };
+    }
+    const durationMs = Date.now() - start;
+    const bytes = htmlByteLength(html, encoder);
+    emitSlotMetric({
+      type: "resolved",
+      slotId: slot.id,
+      durationMs,
+      bytes
+    }, onSlotMetric);
     return {
       html,
-      id: slot.id
+      id: slot.id,
+      durationMs,
+      bytes
     };
   } catch (error) {
+    const durationMs = Date.now() - start;
     onError?.(error, slot);
+    emitSlotMetric({
+      type: error?.__absTimeout === true ? "timeout" : "error",
+      slotId: slot.id,
+      durationMs,
+      error
+    }, onSlotMetric);
     if (typeof slot.errorHtml === "string") {
+      const html = slot.errorHtml;
       return {
-        html: slot.errorHtml,
-        id: slot.id
+        html,
+        id: slot.id,
+        durationMs,
+        bytes: htmlByteLength(html, encoder)
       };
     }
     return {
       html: null,
-      id: slot.id
+      id: slot.id,
+      durationMs,
+      bytes: 0
     };
   }
 };
@@ -30938,23 +31106,37 @@ var streamOutOfOrderSlots = ({
   footerHtml = "",
   headerHtml = "",
   nonce,
+  policy,
+  onSlotMetric,
   onError,
   slots
 }) => {
+  const resolvedPolicy = resolveStreamingSlotPolicy(policy);
+  const combinedOnError = createCombinedSlotErrorHandler(resolvedPolicy.onError, onError);
+  const combinedOnSlotMetric = createCombinedSlotMetricHandler(resolvedPolicy.onSlotMetric, onSlotMetric);
+  const effectivePolicy = {
+    ...resolvedPolicy,
+    onSlotMetric: combinedOnSlotMetric
+  };
+  const preparedSlots = prepareSlots({
+    policy: effectivePolicy,
+    slots,
+    onError: combinedOnError,
+    onSlotMetric: combinedOnSlotMetric
+  });
   const encoder = new TextEncoder;
   return new ReadableStream({
     async start(controller) {
       try {
         let header = headerHtml;
-        if (!header.includes(STREAMING_RUNTIME_GLOBAL)) {
+        if (preparedSlots.length > 0 && !header.includes(STREAMING_RUNTIME_GLOBAL)) {
           header = injectHtmlIntoHead(header, renderStreamingSlotsRuntimeTag(nonce));
         }
         controller.enqueue(toUint8(header, encoder));
-        const pending = slots.map((slot) => {
-          const resolvedSlot = toStreamingSlot(slot);
-          const fallback = renderStreamingSlotPlaceholder(resolvedSlot.id, resolvedSlot.fallbackHtml ?? "");
+        const pending = preparedSlots.map((slot) => {
+          const fallback = renderStreamingSlotPlaceholder(slot.id, slot.fallbackHtml ?? "");
           controller.enqueue(toUint8(fallback, encoder));
-          return resolveSlot(resolvedSlot, onError);
+          return resolveSlot(slot, combinedOnError, effectivePolicy, combinedOnSlotMetric);
         });
         while (pending.length > 0) {
           const { original, result } = await nextResolvedSlot(pending);
@@ -30963,6 +31145,12 @@ var streamOutOfOrderSlots = ({
             pending.splice(index, 1);
           if (result.html === null)
             continue;
+          emitSlotMetric({
+            type: "patched",
+            slotId: result.id,
+            durationMs: result.durationMs,
+            bytes: result.bytes
+          }, combinedOnSlotMetric);
           controller.enqueue(toUint8(renderStreamingSlotPatchTag(result.id, result.html, nonce), encoder));
         }
         if (footerHtml.length > 0) {
@@ -31026,12 +31214,33 @@ var injectStreamingRuntimeIntoStream = (stream, nonce) => {
     }
   });
 };
-var appendStreamingSlotPatchesToStream = (stream, slots = [], { injectRuntime = true, nonce, onError } = {}) => {
+var appendStreamingSlotPatchesToStream = (stream, slots = [], {
+  injectRuntime = true,
+  nonce,
+  onError,
+  onSlotMetric,
+  policy
+} = {}) => {
+  const resolvedPolicy = resolveStreamingSlotPolicy(policy);
+  const combinedOnError = createCombinedSlotErrorHandler(resolvedPolicy.onError, onError);
+  const combinedOnSlotMetric = createCombinedSlotMetricHandler(resolvedPolicy.onSlotMetric, onSlotMetric);
+  const effectivePolicy = {
+    ...resolvedPolicy,
+    onSlotMetric: combinedOnSlotMetric
+  };
+  const preparedSlots = prepareSlots({
+    policy: effectivePolicy,
+    slots,
+    onError: combinedOnError,
+    onSlotMetric: combinedOnSlotMetric
+  });
+  if (preparedSlots.length === 0)
+    return stream;
   const source = injectRuntime ? injectStreamingRuntimeIntoStream(stream, nonce) : stream;
   const encoder = new TextEncoder;
   const decoder = new TextDecoder;
   const reader = source.getReader();
-  const pending = slots.map((slot) => resolveSlot(slot, onError));
+  const pending = preparedSlots.map((slot) => resolveSlot(slot, combinedOnError, effectivePolicy, combinedOnSlotMetric));
   return new ReadableStream({
     async start(controller) {
       let baseDone = false;
@@ -31088,6 +31297,12 @@ var appendStreamingSlotPatchesToStream = (stream, slots = [], { injectRuntime =
             pending.splice(index, 1);
           if (winner.result.html === null)
             continue;
+          emitSlotMetric({
+            type: "patched",
+            slotId: winner.result.id,
+            durationMs: winner.result.durationMs,
+            bytes: winner.result.bytes
+          }, combinedOnSlotMetric);
           controller.enqueue(encoder.encode(renderStreamingSlotPatchTag(winner.result.id, winner.result.html, nonce)));
         }
         if (footer.length > 0)
@@ -31146,13 +31361,14 @@ var cloneHeaders = (response) => {
   const headers = new Headers(response.headers);
   return headers;
 };
-var enhanceHtmlResponseWithStreamingSlots = (response, { nonce, onError, streamingSlots = [] } = {}) => {
+var enhanceHtmlResponseWithStreamingSlots = (response, { nonce, onError, streamingSlots = [], policy } = {}) => {
   if (!response.body || streamingSlots.length === 0) {
     return response;
   }
   const body = appendStreamingSlotPatchesToStream(response.body, streamingSlots, {
     nonce,
-    onError
+    onError,
+    policy
   });
   return new Response(body, {
     headers: cloneHeaders(response),
@@ -31335,5 +31551,5 @@ export {
   AwaitSlot_default as AwaitSlot
 };
 
-//# debugId=1BB7CFD3565A43C264756E2164756E21
+//# debugId=CF6826373193F13564756E2164756E21
 //# sourceMappingURL=index.js.map