@honua/react 0.1.1-beta.0 → 0.1.4-beta.0

package/core/surfaces.js

@@ -774,33 +774,15 @@ export class HonuaOgcFeatures {
         return this.client.listOgcItems({ ...request, ...(layout ? { layout } : {}) });
     }
     async itemsAll(request) {
-        const pageSize = normalizePageSize(request.pageSize, request.limit);
-        const maxPages = normalizeMaxPages(request.maxPages);
-        const offset = normalizeOffset(request.offset);
         const totalLimit = normalizeTotalLimit(request.limit);
         const features = [];
-        for (let page = 0; page < maxPages; page += 1) {
-            if (totalLimit !== undefined && features.length >= totalLimit) {
-                break;
-            }
-            const remainingLimit = totalLimit === undefined ? pageSize : Math.max(0, totalLimit - features.length);
-            if (remainingLimit < 1) {
-                break;
-            }
-            const limit = Math.min(pageSize, remainingLimit);
-            const response = await this.items({
-                ...request,
-                limit,
-                offset: offset + page * pageSize,
-            });
-            const pageFeatures = extractOgcFeatures(response);
-            if (pageFeatures.length === 0) {
-                break;
-            }
-            features.push(...pageFeatures);
-            if (pageFeatures.length < limit) {
-                break;
-            }
+        for await (const page of drainOgcItemPages((pageRequest) => this.items(withOgcItemsPage(request, pageRequest)), {
+            pageSize: normalizePageSize(request.pageSize, request.limit),
+            maxPages: normalizeMaxPages(request.maxPages),
+            startOffset: normalizeOffset(request.offset),
+            ...(totalLimit !== undefined ? { totalLimit } : {}),
+        })) {
+            features.push(...page);
         }
         if (totalLimit !== undefined && features.length > totalLimit) {
             return features.slice(0, totalLimit);
@@ -865,33 +847,15 @@ export class HonuaOgcFeatureCollection {
         });
     }
     async itemsAll(request = {}) {
-        const pageSize = normalizePageSize(request.pageSize, request.limit);
-        const maxPages = normalizeMaxPages(request.maxPages);
-        const offset = normalizeOffset(request.offset);
         const totalLimit = normalizeTotalLimit(request.limit);
         const features = [];
-        for (let page = 0; page < maxPages; page += 1) {
-            if (totalLimit !== undefined && features.length >= totalLimit) {
-                break;
-            }
-            const remainingLimit = totalLimit === undefined ? pageSize : Math.max(0, totalLimit - features.length);
-            if (remainingLimit < 1) {
-                break;
-            }
-            const limit = Math.min(pageSize, remainingLimit);
-            const response = await this.items({
-                ...request,
-                limit,
-                offset: offset + page * pageSize,
-            });
-            const pageFeatures = extractOgcFeatures(response);
-            if (pageFeatures.length === 0) {
-                break;
-            }
-            features.push(...pageFeatures);
-            if (pageFeatures.length < limit) {
-                break;
-            }
+        for await (const page of drainOgcItemPages((pageRequest) => this.items(withOgcItemsPage(request, pageRequest)), {
+            pageSize: normalizePageSize(request.pageSize, request.limit),
+            maxPages: normalizeMaxPages(request.maxPages),
+            startOffset: normalizeOffset(request.offset),
+            ...(totalLimit !== undefined ? { totalLimit } : {}),
+        })) {
+            features.push(...page);
         }
         if (totalLimit !== undefined && features.length > totalLimit) {
             return features.slice(0, totalLimit);
@@ -899,24 +863,13 @@ export class HonuaOgcFeatureCollection {
         return features;
     }
     async *itemsStream(request = {}) {
-        const pageSize = normalizePageSize(request.pageSize, request.limit);
-        const maxPages = normalizeMaxPages(request.maxPages);
-        const offset = normalizeOffset(request.offset);
-        for (let page = 0; page < maxPages; page += 1) {
-            const response = await this.items({
-                ...request,
-                limit: pageSize,
-                offset: offset + page * pageSize,
-            });
-            const pageFeatures = extractOgcFeatures(response);
-            if (pageFeatures.length === 0) {
-                break;
-            }
-            yield pageFeatures;
-            if (pageFeatures.length < pageSize) {
-                break;
-            }
-        }
+        // The stream yields every page the drain produces; `limit` selects the
+        // page size here (as it always has) rather than capping the total.
+        yield* drainOgcItemPages((pageRequest) => this.items(withOgcItemsPage(request, pageRequest)), {
+            pageSize: normalizePageSize(request.pageSize, request.limit),
+            maxPages: normalizeMaxPages(request.maxPages),
+            startOffset: normalizeOffset(request.offset),
+        });
     }
     async item(request) {
         const layout = await this.layout();
@@ -1974,6 +1927,258 @@ function normalizeTotalLimit(limit) {
     }
     return limit;
 }
+/**
+ * Query-string keys on an OGC API Features `rel="next"` link that must not be
+ * replayed on the follow-up request: the drain owns the page size (`limit`)
+ * and the caller owns the response format (`f`). Every other param on the
+ * link — `offset` / `startindex` on an offset server, an opaque
+ * `token` / `cursor` / `next` on a cursor server — is the server's own paging
+ * state and is echoed back verbatim, subject to the stale-offset rules in
+ * {@link ogcCursorFromHref}.
+ */
+const OGC_NEXT_LINK_RESERVED_PARAMS = new Set(["f", "limit"]);
+/**
+ * Params that express a numeric start position. Compared case-insensitively:
+ * `offset` is Honua Server's spelling, `startindex` / `startIndex` the OGC API
+ * spelling servers vary the casing of.
+ */
+const OGC_OFFSET_PARAM_NAMES = new Set(["offset", "startindex"]);
+/**
+ * Params that express an opaque paging cursor. Matched case-insensitively with
+ * `-` / `_` stripped, so `page_token` and `pageToken` both hit. When one of
+ * these drives the next link, the token owns the read position and any
+ * `offset` / `startindex` on the same link is a stale echo of the request the
+ * server just answered.
+ */
+const OGC_CURSOR_PARAM_NAMES = new Set([
+    "token",
+    "nexttoken",
+    "pagetoken",
+    "continuationtoken",
+    "resumptiontoken",
+    "cursor",
+    "next",
+    "page",
+    "searchafter",
+    "scroll",
+    "scrollid",
+]);
+/** Base used only to parse relative `rel="next"` hrefs; never requested. */
+const OGC_NEXT_LINK_PARSE_BASE = "https://placeholder.test";
+/**
+ * Page `/items` the way OGC API Features Core specifies: follow the
+ * `rel="next"` link the server returns, and only fall back to `limit`/`offset`
+ * arithmetic when the response advertises no usable next link. Offset
+ * arithmetic alone silently mis-pages every server that pages by opaque token
+ * or cursor (pgstac-backed APIs, several pygeoapi deployments): the cursor is
+ * dropped, so pages repeat or skip with no error.
+ *
+ * Anti-corruption invariants, preserved on both paths:
+ * - an empty page ends the drain;
+ * - a page whose feature identity repeats an already-yielded page is dropped
+ *   and ends the drain, so a looping server can never duplicate features;
+ * - a `rel="next"` link that repeats a cursor already followed is treated as
+ *   a stalled pager and ends the drain;
+ * - a stale `offset` / `startindex` echoed on a cursor link never reaches the
+ *   wire beside the cursor (see {@link ogcCursorFromHref});
+ * - `maxPages` still caps the total number of requests.
+ *
+ * On the link-driven path a short page is deliberately *not* a stop signal:
+ * OGC API Features permits a server to return fewer than `limit` items on a
+ * non-final page while still advertising `rel="next"` (the same tolerance the
+ * Records drain applies). On the offset path a short page still ends the
+ * drain, as it always has.
+ */
+async function* drainOgcItemPages(fetchPage, options) {
+    const { pageSize, maxPages, startOffset, totalLimit } = options;
+    const seenCursorKeys = new Set();
+    const seenPageKeys = new Set();
+    let cursor;
+    let emitted = 0;
+    for (let page = 0; page < maxPages; page += 1) {
+        const remaining = totalLimit === undefined ? pageSize : Math.max(0, totalLimit - emitted);
+        if (remaining < 1) {
+            break;
+        }
+        const limit = Math.min(pageSize, remaining);
+        // A server cursor carries its own position; re-sending the computed offset
+        // alongside it is what makes token pagers skip rows.
+        const sentOffset = cursor === undefined ? startOffset + page * pageSize : undefined;
+        const response = await fetchPage({
+            limit,
+            offset: sentOffset,
+            cursorParams: cursor?.params,
+        });
+        const pageFeatures = extractOgcFeatures(response);
+        if (pageFeatures.length === 0) {
+            break;
+        }
+        const pageKey = ogcPageIdentityKey(pageFeatures);
+        if (pageKey !== undefined) {
+            if (seenPageKeys.has(pageKey)) {
+                break;
+            }
+            seenPageKeys.add(pageKey);
+        }
+        yield pageFeatures;
+        emitted += pageFeatures.length;
+        const next = ogcNextItemsCursor(response.links, sentOffset);
+        if (next !== undefined) {
+            if (seenCursorKeys.has(next.key)) {
+                break;
+            }
+            seenCursorKeys.add(next.key);
+            cursor = next;
+            continue;
+        }
+        if (cursor !== undefined) {
+            // Link-driven drain and the server stopped advertising a next link:
+            // that is the spec's end-of-results signal.
+            break;
+        }
+        if (pageFeatures.length < limit) {
+            break;
+        }
+    }
+}
+/**
+ * Merge one {@link drainOgcItemPages} page request onto the caller's request.
+ * Cursor params ride on `extraParams`, which the OGC wire layer serializes
+ * before the typed fields, so the caller's `filter` / `bbox` / `crs` still win
+ * and only the paging state comes from the server.
+ */
+function withOgcItemsPage(request, page) {
+    return {
+        ...request,
+        limit: page.limit,
+        offset: page.offset,
+        ...(page.cursorParams ? { extraParams: { ...request.extraParams, ...page.cursorParams } } : {}),
+    };
+}
+/**
+ * Resolve the server's next-page cursor from an `/items` response. Only the
+ * link's query params are replayed (not its host or path), so a next link
+ * rewritten by a proxy — or emitted with the server's internal hostname —
+ * still pages correctly. Returns `undefined` when no `rel="next"` link carries
+ * usable paging state, which is what selects the offset fallback.
+ *
+ * @param sentOffset the `offset` sent for the page that produced these links,
+ *   or `undefined` when a cursor already drove that request. Used to spot an
+ *   `offset` on the link that merely echoes the request just answered.
+ */
+function ogcNextItemsCursor(links, sentOffset) {
+    if (!links) {
+        return undefined;
+    }
+    for (const link of links) {
+        if (link.rel !== "next" || typeof link.href !== "string") {
+            continue;
+        }
+        // An HTML alternate of the next page carries the same cursor but is not
+        // the representation we are draining; prefer a data link when both exist.
+        if (typeof link.type === "string" && link.type.includes("html")) {
+            continue;
+        }
+        const cursor = ogcCursorFromHref(link.href, sentOffset);
+        if (cursor !== undefined) {
+            return cursor;
+        }
+    }
+    return undefined;
+}
+/** Fold a query-param name to its comparison form (case / `-` / `_` insensitive). */
+function ogcParamKey(name) {
+    let folded = "";
+    for (const char of name) {
+        if (char === "-" || char === "_")
+            continue;
+        folded += char.toLowerCase();
+    }
+    return folded;
+}
+/**
+ * Lift the paging state off one `rel="next"` href.
+ *
+ * Servers routinely build the next link by preserving the query string of the
+ * request they just answered and appending their cursor, so the link can carry
+ * both a stale `offset=0` and a live `token=…`. Replaying both is exactly the
+ * mis-paging this drain exists to prevent — a server that honors `offset`
+ * alongside its own token re-reads or skips a page. Two rules keep the two
+ * paging styles apart:
+ *
+ * 1. an opaque cursor on the link (`token`, `cursor`, `next`, `page`, …) owns
+ *    the read position, so every `offset` / `startindex` on that link is
+ *    dropped;
+ * 2. otherwise an `offset` / `startindex` that merely repeats the offset just
+ *    sent cannot advance the drain, so it is dropped too — and if that leaves
+ *    the link with nothing, the drain falls back to offset arithmetic.
+ *
+ * A genuine offset link (`offset=10` after requesting `offset=0`) is kept and
+ * drives the next page, which is what pygeoapi / ldproxy deployments emit.
+ */
+function ogcCursorFromHref(href, sentOffset) {
+    let url;
+    try {
+        url = new URL(href, OGC_NEXT_LINK_PARSE_BASE);
+    }
+    catch {
+        return undefined;
+    }
+    const candidates = [];
+    let hasOpaqueCursor = false;
+    for (const [key, value] of url.searchParams) {
+        if (OGC_NEXT_LINK_RESERVED_PARAMS.has(key)) {
+            continue;
+        }
+        if (OGC_CURSOR_PARAM_NAMES.has(ogcParamKey(key))) {
+            hasOpaqueCursor = true;
+        }
+        candidates.push([key, value]);
+    }
+    const params = {};
+    let hasPagingState = false;
+    for (const [key, value] of candidates) {
+        const folded = ogcParamKey(key);
+        if (OGC_OFFSET_PARAM_NAMES.has(folded)) {
+            if (hasOpaqueCursor) {
+                continue;
+            }
+            if (sentOffset !== undefined && Number(value) === sentOffset) {
+                continue;
+            }
+            hasPagingState = true;
+        }
+        else if (OGC_CURSOR_PARAM_NAMES.has(folded)) {
+            hasPagingState = true;
+        }
+        params[key] = value;
+    }
+    // Everything that survived is an echo of the query we just sent (`bbox`,
+    // `filter`, `sortby`, …): the link advertises no forward progress, so the
+    // offset arithmetic below stays in charge rather than re-reading this page.
+    if (!hasPagingState) {
+        return undefined;
+    }
+    const entries = Object.entries(params).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return { key: entries.map(([key, value]) => `${key}=${value}`).join("&"), params };
+}
+/**
+ * Cheap identity signature for one `/items` page, used to detect a server that
+ * replays a page it already returned. Returns `undefined` when any feature
+ * lacks a GeoJSON `id`, in which case the drain simply skips the check rather
+ * than serializing whole geometries.
+ */
+function ogcPageIdentityKey(features) {
+    const ids = [];
+    for (const feature of features) {
+        const id = feature?.id;
+        if (typeof id !== "string" && typeof id !== "number") {
+            return undefined;
+        }
+        ids.push(String(id));
+    }
+    return JSON.stringify(ids);
+}
 function isFinitePositiveInteger(value) {
     return typeof value === "number" && Number.isFinite(value) && Math.trunc(value) > 0;
 }

package/core/types.d.ts

@@ -540,9 +540,33 @@ export interface HonuaClientOptions {
     transport?: HonuaTransport;
 }
 export interface HonuaRetryOptions {
+    /**
+     * Maximum number of transient-failure retry attempts after the initial
+     * request. Retry is entirely opt-in: values below `1` (including the default
+     * `0`) disable the retry loop, so no status, network, or timeout failure is
+     * replayed.
+     *
+     * This option does not govern the authentication replay. When an
+     * {@link HonuaClientOptions.auth} provider is configured, a replay-safe
+     * request (`GET` / `HEAD` / `PUT` / `DELETE`) answered with `401` or `403` is
+     * still reissued once after a forced credential refresh, even with retries
+     * disabled. Instrumentation that counts requests should expect that one extra
+     * attempt.
+     */
     maxRetries?: number;
+    /** First backoff delay in milliseconds; doubles per attempt. Default: `100`. */
     baseDelayMs?: number;
+    /** Upper bound on any single backoff delay, including a server `Retry-After`. Default: `2000`. */
     maxDelayMs?: number;
+    /**
+     * HTTP statuses the loop replays on replay-safe methods
+     * (`GET` / `HEAD` / `PUT` / `DELETE`). Default: `[429, 502, 503, 504]` — the
+     * statuses that explicitly invite the same request again. This is
+     * intentionally narrower than the broader `408, 429, 500, 502, 503, 504` set
+     * that {@link HonuaHttpError} classifies as transient `retryable` metadata:
+     * that classification is descriptive and never initiates a retry. Pass the
+     * broader set here to opt into replaying `408` / `500`.
+     */
     retryStatuses?: readonly number[];
 }
 export interface HonuaCompatibilityRequest {
@@ -1118,6 +1142,17 @@ export interface HonuaOgcLink {
     rel?: string;
     type?: string;
     title?: string;
+    /**
+     * HTTP method the link target expects. STAC API uses it on the landing
+     * page (`rel="search"` advertised for `GET` and/or `POST`) and on
+     * pagination links (a `POST` `rel="next"` carries its cursor in `body`
+     * rather than on the href query string).
+     */
+    method?: string;
+    /** Request-body members a `POST` link contributes to the next request. */
+    body?: Record<string, unknown>;
+    /** When true, `body` merges over the originating request body. */
+    merge?: boolean;
 }
 /** Response from the OGC API landing page (`/ogc/features`). */
 export interface HonuaOgcLandingResponse {
@@ -1363,12 +1398,21 @@ export interface HonuaOgcProcessJobStatus {
     };
 }
 /**
- * Process-execution request envelope. honua-server advertises
- * `jobControlOptions: ['async-execute', 'dismiss']` and rejects any
- * `response` other than `document` with HTTP 501 — the SDK type mirrors
- * that supported surface (no `sync` mode, no `raw` response). `mode: "auto"`
- * omits the `Prefer` header so the server applies its default; `"async"`
- * sends `Prefer: respond-async` explicitly.
+ * Process-execution request envelope for `POST /processes/{id}/execution`
+ * (OGC API — Processes Part 1: Core §7.11).
+ *
+ * `mode` selects the RFC 7240 preference the SDK sends:
+ *
+ * - `"async"` → `Prefer: respond-async`. A conformant server answers `201` with
+ *   a `Location` header and a `statusInfo` body.
+ * - `"sync"` → no `Prefer` header, and the caller asserts the process declares
+ *   `sync-execute`. A conformant server answers `200` with the results document.
+ * - `"auto"` (default) → no `Prefer` header; whichever shape the server returns
+ *   is adapted onto the same `IJobRun` surface.
+ *
+ * Core defines no header that *forces* synchronous execution, so `"sync"` is a
+ * preference plus a capability assertion, never a guarantee: a server that
+ * answers a `"sync"` request with a job still yields a pollable `IJobRun`.
  */
 export interface OgcProcessExecuteRequest {
     processId: string;
@@ -1379,19 +1423,76 @@ export interface OgcProcessExecuteRequest {
             mediaType?: string;
         };
     }>;
-    /** `async-execute` returns a job; `auto` lets the server pick (always async on Honua). */
-    mode?: "async" | "auto";
+    /** Execution preference; see the interface docs. Defaults to `"auto"`. */
+    mode?: "sync" | "async" | "auto";
+    /**
+     * The process's advertised `jobControlOptions` (from `describe()` or a
+     * discovery snapshot). Supplied — or already memoized from a `describe()` on
+     * the same handle — it lets `mode` be gated against what the process actually
+     * declares, so an undeclared `sync-execute` / `async-execute` fails closed with
+     * `HonuaCapabilityNotSupportedError` instead of being posted blindly.
+     */
+    jobControlOptions?: readonly string[];
     headers?: HeadersInit;
     signal?: AbortSignal;
+    /**
+     * Raw endpoint path prefix (defaults to the Honua facade `/ogc/processes`). A
+     * raw third-party Processes service root discovered by `discoverOgcProcesses()`
+     * threads its service-root path here so the execution route resolves against
+     * the advertised layout instead of the facade.
+     */
+    basePath?: string;
+}
+/**
+ * Request envelope for the OGC API Processes job routes (status, results,
+ * dismiss). Carries the same `basePath` seam as the metadata requests so a job
+ * created against a raw service root keeps polling that root.
+ */
+export interface OgcProcessJobRequest {
+    jobId: string;
+    signal?: AbortSignal;
+    responseFormat?: string;
+    extraParams?: Record<string, string | number | boolean>;
+    /** Raw endpoint path prefix (defaults to the Honua facade `/ogc/processes`). */
+    basePath?: string;
+    /**
+     * Server-advertised route for this job resource, already reduced to a
+     * same-origin request path. When present it replaces the Core-templated
+     * `{basePath}/jobs/{jobId}[/results]` route so the lifecycle follows the
+     * server's own `Location` header and `links[]` rather than a guessed path.
+     */
+    routePath?: string;
 }
-/** Job descriptor returned when the server accepted an async execution. */
+/**
+ * Outcome of `POST /processes/{id}/execution`.
+ *
+ * The same envelope carries both Core response shapes so one typed surface
+ * covers a raw third-party server and the Honua facade:
+ *
+ * - asynchronous — `jobID` names the created job and `synchronous` is `false`.
+ * - synchronous — the server answered `200` with the results document inline.
+ *   `jobID` is `""` (Core assigns no job identifier to a synchronous
+ *   execution), `status` is `"successful"`, `synchronous` is `true`, and
+ *   `results` holds the document.
+ */
 export interface HonuaOgcProcessJobAccepted {
+    /** Server-assigned job id; `""` for a synchronous execution (no job exists). */
     jobID: string;
     status: OgcProcessStatus;
     processID?: string;
     links?: HonuaOgcLink[];
     /** Initial (often `accepted` or `running`) status payload, when reported. */
     statusInfo?: HonuaOgcProcessJobStatus;
+    /**
+     * Same-origin request path derived from the async `Location` header (or the
+     * accepted document's `self` link). Polling follows it instead of templating
+     * `{basePath}/jobs/{jobId}`.
+     */
+    statusPath?: string;
+    /** Results document, populated only when `synchronous` is `true`. */
+    results?: HonuaOgcProcessJobResults;
+    /** `true` when the server answered inline with the results document. */
+    synchronous?: boolean;
 }
 /**
  * Result document returned from `/jobs/{jobId}/results`. OGC API Processes
@@ -1422,6 +1523,19 @@ export interface StacSearchRequest {
      * advertise an opaque `?next=…` token instead of `offset`.
      */
     next?: string;
+    /**
+     * Opaque continuation query params captured verbatim from a server
+     * `rel="next"` link whose cursor is neither `offset` nor `next` (pgstac /
+     * stac-fastapi emit `?token=next:…`). Merged over the serialized search
+     * params so the next page is requested exactly the way the server asked.
+     */
+    nextParams?: Readonly<Record<string, string>>;
+    /**
+     * Opaque continuation body members captured from a `POST` `rel="next"`
+     * link (`{ "method": "POST", "body": { "token": "next:…" }, "merge": true }`).
+     * Merged over the serialized `POST /search` body.
+     */
+    nextBody?: Readonly<Record<string, unknown>>;
     /** Subset of asset / item properties to return. */
     fields?: {
         include?: readonly string[];