@authhero/proxy 0.5.1 → 0.7.0

package/dist/proxy.d.ts

@@ -1,6 +1,6 @@
 import { ProxyRoute, ProxyRoutesAdapter, CacheAdapter, RouteMatch, HandlerConfig } from '@authhero/adapter-interfaces';
 export { HandlerConfig, ListProxyRoutesParams, ListProxyRoutesResult, ProxyRoute, ProxyRouteInsert, ProxyRouteUpdate, ProxyRoutesAdapter, RouteMatch, handlerConfigSchema, matchSchema, proxyRouteInsertSchema, proxyRouteSchema, proxyRouteUpdateSchema } from '@authhero/adapter-interfaces';
-import { MiddlewareHandler, Hono, Context } from 'hono';
+import { MiddlewareHandler, Context, Hono } from 'hono';
 import { z } from '@hono/zod-openapi';
 
 interface ResolvedHost {
@@ -28,6 +28,7 @@ interface HostResolverCache {
 interface HostCacheOptions {
     freshTtlMs: number;
     staleTtlMs?: number;
+    staleIfErrorTtlMs?: number;
     negativeTtlMs?: number;
     maxEntries?: number;
     waitUntil?: (promise: Promise<unknown>) => void;
@@ -53,26 +54,34 @@ declare class HandlerRegistry {
 }
 declare function defineHandler<TOptions>(def: HandlerDefinition<TOptions>): HandlerDefinition<TOptions>;
 
-interface ProxyAppOptions {
+interface ProxyRouteHandlerSpec {
+    type: string;
+    options?: unknown;
+}
+interface ProxyDataPlaneOptions {
     data: ProxyDataAdapter;
     cacheTtlMs?: number;
     cache?: HostCacheOptions;
     resolver?: HostResolverCache;
     registry?: HandlerRegistry;
     bindings?: Record<string, unknown>;
+    resolveHostTimeoutMs?: number;
+    defaultHandlers?: ProxyRouteHandlerSpec[];
 }
-declare function createProxyApp(options: ProxyAppOptions): Hono;
+declare function createProxyDataPlaneHandler(options: ProxyDataPlaneOptions): (c: Context) => Promise<Response>;
+declare function createProxyDataPlaneRouter(options: ProxyDataPlaneOptions): Hono;
 
-interface ProxyDataPlaneOptions {
+interface ProxyAppOptions {
     data: ProxyDataAdapter;
     cacheTtlMs?: number;
     cache?: HostCacheOptions;
     resolver?: HostResolverCache;
     registry?: HandlerRegistry;
     bindings?: Record<string, unknown>;
+    resolveHostTimeoutMs?: number;
+    defaultHandlers?: ProxyRouteHandlerSpec[];
 }
-declare function createProxyDataPlaneHandler(options: ProxyDataPlaneOptions): (c: Context) => Promise<Response>;
-declare function createProxyDataPlaneRouter(options: ProxyDataPlaneOptions): Hono;
+declare function createProxyApp(options: ProxyAppOptions): Hono;
 
 interface CacheApiHostCacheOptions {
     upstream: HostResolverCache;
@@ -81,6 +90,8 @@ interface CacheApiHostCacheOptions {
     namespace?: string;
     cache?: Cache;
     waitUntil?: (promise: Promise<unknown>) => void;
+    cacheReadTimeoutMs?: number;
+    cacheWriteTimeoutMs?: number;
 }
 /**
  * Wraps an upstream `HostResolverCache` with a Cloudflare Cache-API layer.
@@ -93,8 +104,8 @@ interface CacheApiHostCacheOptions {
  *
  * @deprecated Prefer `createCacheAdapterHostCache` with `createCloudflareCache`
  * from `@authhero/cloudflare-adapter`. The adapter-based wrapper supports
- * stale-while-revalidate and works with any `CacheAdapter` (Cloudflare,
- * Redis, in-memory, …).
+ * stale-while-revalidate, stale-if-error, and works with any `CacheAdapter`
+ * (Cloudflare, Redis, in-memory, …).
  */
 declare function createCacheApiHostCache(options: CacheApiHostCacheOptions): HostResolverCache;
 declare function buildCacheApiKey(namespace: string, host: string): Request;
@@ -104,15 +115,19 @@ interface CacheAdapterHostCacheOptions {
     cache: CacheAdapter;
     freshTtlMs: number;
     staleTtlMs?: number;
+    staleIfErrorTtlMs?: number;
     negativeTtlMs?: number;
     keyPrefix?: string;
     waitUntil?: (promise: Promise<unknown>) => void;
+    cacheReadTimeoutMs?: number;
+    cacheWriteTimeoutMs?: number;
 }
 /**
  * Wraps an upstream `HostResolverCache` with a generic `CacheAdapter` layer.
- * Adds stale-while-revalidate semantics on top of any cache implementation
- * — Cloudflare Cache API (via `CloudflareCache` from `@authhero/cloudflare-adapter`),
- * Redis, in-memory, or anything else satisfying the `CacheAdapter` interface.
+ * Adds stale-while-revalidate and stale-if-error semantics on top of any
+ * cache implementation — Cloudflare Cache API (via `CloudflareCache` from
+ * `@authhero/cloudflare-adapter`), Redis, in-memory, or anything else
+ * satisfying the `CacheAdapter` interface.
  *
  * Typical use on Cloudflare Workers:
  *
@@ -126,6 +141,7 @@ interface CacheAdapterHostCacheOptions {
  *   cache,
  *   freshTtlMs: 60 * 60_000,           // 1 hour fresh
  *   staleTtlMs: 23 * 60 * 60_000,      // SWR for 23 more hours (24h total)
+ *   staleIfErrorTtlMs: 24 * 60 * 60_000, // serve last-known-good for one more day on upstream errors
  *   waitUntil: (p) => ctx.waitUntil(p),
  * });
  * ```
@@ -187,6 +203,7 @@ declare const serviceBindingHandler: HandlerDefinition<{
     binding: string;
     preserve_host: boolean;
     upstream_url?: string | undefined;
+    timeout_ms?: number | undefined;
 }>;
 
 declare const dispatchNamespaceHandler: HandlerDefinition<{
@@ -194,6 +211,7 @@ declare const dispatchNamespaceHandler: HandlerDefinition<{
     script_name: string;
     cpu_ms?: number | undefined;
     subrequests?: number | undefined;
+    timeout_ms?: number | undefined;
 }>;
 
 declare const redirectHandler: HandlerDefinition<{
@@ -226,8 +244,12 @@ interface ProxyHostContext {
  * `domain` set in its Hono context (read with `getProxy*` helpers from
  * `handlers/util.ts`). Handlers that template against those values
  * (`dispatch_namespace`) depend on this wiring.
+ *
+ * `defaultHandlers` is a prebuilt middleware chain installed as the catch-all
+ * when no per-host route matches. Pass `undefined` to keep the legacy 404
+ * "No matching route" behavior.
  */
-declare function compileHostApp(routes: ProxyRoute[], registry: HandlerRegistry, hostContext?: ProxyHostContext): Hono;
+declare function compileHostApp(routes: ProxyRoute[], registry: HandlerRegistry, hostContext?: ProxyHostContext, defaultHandlers?: MiddlewareHandler[]): Hono;
 
 declare function sortRoutes(routes: ProxyRoute[]): ProxyRoute[];
 /**
@@ -303,4 +325,4 @@ declare function createHttpProxyAdapter(options: HttpProxyAdapterOptions): Proxy
 declare const PROXY_RESOLVE_HOST_SCOPE = "proxy:resolve_host";
 
 export { HandlerRegistry, PROXY_RESOLVE_HOST_SCOPE, basicAuthHandler, buildCacheAdapterKey, buildCacheApiKey, buildMatchFilter, cacheHandler, compileHostApp, corsHandler, createCacheAdapterHostCache, createCacheApiHostCache, createHttpProxyAdapter, createInMemoryHostCache, createProxyApp, createProxyDataPlaneHandler, createProxyDataPlaneRouter, createStaticProxyAdapter, defineHandler, dispatchNamespaceHandler, forwardedHeadersHandler, headersHandler, httpHandler, httpRoute, matchesAnyHost, matchesHost, redirectHandler, registerBuiltinHandlers, rewriteCookiesHandler, rewriteLocationHandler, serviceBindingHandler, sortRoutes, staticHandler };
-export type { CacheAdapterHostCacheOptions, CacheApiHostCacheOptions, HandlerBuildContext, HandlerDefinition, HostCacheOptions, HostResolverCache, HttpProxyAdapterOptions, ProxyAppOptions, ProxyDataAdapter, ProxyDataPlaneOptions, ResolvedHost, StaticHostConfig, StaticProxyAdapterOptions, StaticRouteInput };
+export type { CacheAdapterHostCacheOptions, CacheApiHostCacheOptions, HandlerBuildContext, HandlerDefinition, HostCacheOptions, HostResolverCache, HttpProxyAdapterOptions, ProxyAppOptions, ProxyDataAdapter, ProxyDataPlaneOptions, ProxyRouteHandlerSpec, ResolvedHost, StaticHostConfig, StaticProxyAdapterOptions, StaticRouteInput };