import type { Context, Env, MiddlewareHandler } from 'hono';
import type * as Store from './Store.js';
/**
 * Per-request edge-cache policy published by `Cache.response` for routes that
 * opted into response caching. Its presence is what marks a response as safe to
 * persist in the shared edge cache.
 */
export type Policy = {
    /** Shared max-age / s-maxage in seconds for the stored response. */
    maxAge: number;
    /** Stale-while-revalidate window in seconds, if any. */
    staleWhileRevalidate?: number | undefined;
};
/** Hono variables published by the edge-cache layer. */
export type Variables = {
    /** Edge-cache policy for the current route, set by `Cache.response`. */
    edgeCache?: Policy | undefined;
    /** `'hit'` when the edge cache served the response without reaching the origin handlers. */
    edgeCacheStatus?: 'hit' | undefined;
};
/**
 * Serves GET responses from the edge cache store BEFORE auth and rate-limiting
 * run, so cache hits skip the per-request store round-trips that dominate
 * latency. Credential-bearing requests bypass this layer so per-key policy
 * enforcement always runs. Place this ahead of the auth middleware.
 *
 * Only 2xx responses from routes that opted into caching (via `Cache.response`,
 * which publishes the `edgeCache` policy) are stored, and the policy is only
 * published for routes whose responses are public and URL-keyed (no per-principal
 * data), so a single shared entry is safe to serve to all callers. The trade-off
 * is that cache hits bypass origin metering: they are not counted against
 * rate-limit quotas.
 *
 * Lookups are equally scoped: only requests whose matched route carries the
 * {@link markCacheable} marker (applied by `Cache.response`) pay the store
 * read, so GETs to non-cacheable routes skip the round trip entirely.
 *
 * The cache is a plain `Store.Store` — the same store the origin read cache uses
 * — holding the response serialized to a string under a URL key. It is a no-op
 * when no store is supplied.
 *
 * Standard request `Cache-Control` directives let a caller invalidate without an
 * out-of-band purge: `no-cache` forces a refresh (skip the stored hit, re-fetch,
 * overwrite the entry) and `no-store` bypasses the cache entirely. Both fall
 * through to the origin and are metered normally. The store is colo-local, so a
 * refresh only affects the data center serving that request.
 */
export declare function middleware<environment extends Env>(options?: middleware.Options): MiddlewareHandler<environment>;
/**
 * Marks a route handler/middleware as publishing an edge-cache policy, so
 * {@link middleware} looks its route up in the edge cache. `Cache.response`
 * applies it; routes composed any other way never enter the shared cache.
 */
export declare function markCacheable<const handler extends (...args: never[]) => unknown>(handler: handler, options?: markCacheable.Options): handler;
export declare namespace markCacheable {
    /** Options for marking a route as edge-cacheable. */
    type Options = {
        /** Cache key generator. Defaults to the request URL. */
        key?: ((c: Context) => Promise<string> | string) | undefined;
    };
}
/** Adds a request eligibility check; every check must permit caching. */
export declare function setEligibility<const handler extends (...args: never[]) => unknown>(handler: handler, predicate: (c: Context) => boolean): handler;
export declare namespace middleware {
    /** Options for the edge-cache middleware. */
    type Options = {
        /** Store backing the edge cache. The layer is a no-op when omitted. */
        store?: Store.Store | undefined;
    };
}
/**
 * Builds the shared-cache `Cache-Control` value for a stored copy: `public`
 * with `max-age`/`s-maxage` bound to the policy plus an optional
 * `stale-while-revalidate` window. Used for this layer's stored copies and by
 * `Cache.response` to bound the inner response cache's entry lifetime.
 */
export declare function cacheControl(policy: Policy): string;
//# sourceMappingURL=EdgeCache.d.ts.map