Native resource policies and request plans

This guide describes development SDK and library sources, with ABI version 1. Shared Rust code validates configuration and plans requests. Browser main-thread and strict Worker runtimes use that planner. Native libraries expose configuration, planning and resource polling; hosts execute HTTP, waiting, caching and cancellation. Desktop execution and common script configuration are connected; the mobile application host remains pending. Configuring the library does not start HTTP by itself.

Download the complete C example, header and version manifest. The example supplies controlled style responses and reads actual rendered pixels, without public networking. See also browser policies and native resource delivery.

Configuration and queries

Check SQSM_MAP_RESOURCE_POLICY (1073741824) in sqsm_map_runtime_flags() or nativeResourcePolicy in capability JSON. Call sqsm_map_resource_policy_json on the map creation thread. Inputs are UTF-8 JSON; release outputs using sqsm_map_bytes_free.

{"method":"configure","args":[{"resourceTimeoutMs":20000,"resourcePolicy":{"maxConcurrentRequests":8,"attemptTimeoutMs":4000,"retries":1,"retryDelayMs":100,"cache":"default","fallbacks":[{"prefix":"https://primary.example/tiles/","replacements":["https://backup.example/tiles/"],"resourceTypes":["Tile"],"forwardQuery":false}]}}]}

Configuration replaces the whole object; omitted fields reset to defaults. configure returns the new snapshot and emits sqs.resourceschange. Validation, event reservation or output allocation failure preserves the previous configuration. getConfiguration with args: [] reads it. Read-only plan accepts one query; it performs no HTTP or map mutation:

{"method":"plan","args":[{"url":"https://primary.example/tiles/1/2/3?token=private","resourceType":"Tile","maxBytes":8388608,"method":"GET","forceNoStore":false}]}

Input/output limits are 512 KiB / 1 MiB. Unknown fields, invalid types and ranges are rejected. Configuration ranges match browser policies. Query budgets are 1–64 MiB; methods contain 1–32 ASCII letters. Resource kinds use ResourceType vocabulary.

Executing plans

Non-cancel, non-WebSocket resource polling entries include requestPlan, capturing configuration at delivery. Later configuration changes do not alter delivered plans. Version 1 contains urls, method, resourceType, maxBytes, maxConcurrentRequests, resourceTimeoutMs, attemptTimeoutMs, retries, retryDelayMs, optional cache, and retryOn. HTTP(S) URLs cannot contain embedded credentials.

Try URLs in order, with at most 1 + retries attempts per URL. Only GET/HEAD connection failures, attempt timeouts and HTTP 408/429/5xx allow retry or fallback. retryOn states those conditions; all are disabled for POST. Read/decode failure, byte limits, cancellation and permanent 4xx do not fall back. The total deadline includes all candidates, waits and reads; each attempt is limited by the remaining total budget. Concurrency slots include retry waits. There is no exponential backoff or Retry-After handling.

The first matching path/type rule wins, with at most four candidates and twelve attempts. Fallback preserves the encoded path suffix but drops query and fragment by default; only forwardQuery: true forwards the query. Derive headers independently for every candidate. Never carry authorization headers to another origin; automatic tokens require an exact allowlisted final origin. Live HTTP forces no-store. Plans contain no tokens, headers or cache implementation.

C polling plans cap maxBytes at both the core resource budget and the C response interface's 8 MiB limit. The generic read-only planner's 64 MiB limit does not enlarge response limits. Cancel entries have no plan: hosts must stop the relevant task and wait. Map identity and generation checks still reject late responses. WebSocket uses its separate session protocol.

Rust and WASM

Rust uses ResourceConfiguration::parse(serde_json::Value) and plan_json in sqs_map::resource_policy. Parsed configuration fields cannot be directly mutated. Planning needs no HTTP client, GPU, UI or GDAL.

Matching WASM bindings export global resourcePolicyPlanJSON(configurationJSON, queryJSON). Initialize bindings first; it returns plan JSON with stable error codes on failure. No map or GPU is required. Browser Runtime uses this planner. Custom older bindings without that function retain the existing TypeScript planner; that fallback is not evidence of Rust planning.

Verification scope

Fifty real C/WASM input cases agree. A local native HTTP host and actual software Vulkan exercise atomic configuration, captured requests, 503 retry/fallback, deadlines, byte limits and cancellation. Main-thread and strict Worker software GL pass 68 checks and two imagery frames, with actual Rust-planner invocation confirmed. Nineteen existing native resource/script regressions also pass. This does not substitute for public providers, hardware, Windows/macOS, mobile devices or a formal binary release.

Common scripts and host capabilities

Native one-shot and persistent scripts support map.sqs.resources.configure / getConfiguration / plan; await configuration calls. In persistent sessions, sqs.resourceschange includes context: resourcePolicy and deeply immutable resourceConfiguration. Native resource cleanup may also emit a state event with this name, so inspect context. Historical snapshots remain unchanged after replacement. C JSON events contain the snapshot under resourcePolicyEvent; persistent scripts flatten it into the common fields.

resourcePolicyPlanning and resourcePolicyEvents are true; native-library resourcePolicyExecution is false because its external host executes HTTP. Desktop/browser hosts automatically execute the shared planner without changing library dependency boundaries. The same configuration script passes 30 checks in native one-shot/persistent, desktop and browser main-thread/strict Worker routes. Persistent event routes pass nine snapshot, identity, once and unsubscribe checks. See the shared facade and resource policies for examples and cache/application scope.

13.6b connects shared custom-protocol planning and tile templates with original URI/response identities; see custom planning for host registration, budgets and scope.