type: reference title: "Zarr client" description: "Experimental client for Honua Server's versioned Zarr registration and tile-serving contract, reusing an existing HonuaClient for auth, retries, timeouts and interceptors." resource: "honua://capability/raster.multidim-coverage"

Zarr client

@honua/sdk-js/zarr is an experimental client for Honua Server's versioned Zarr registration and tile-serving contract. It reuses an existing HonuaClient, so API keys, bearer tokens, cancellation, retry policy, timeout, and request interceptors remain active.

import { HonuaClient } from "@honua/sdk-js/honua";
import { createZarrClient } from "@honua/sdk-js/zarr";

const client = new HonuaClient({
  baseUrl: "https://your-honua-server.example",
  apiKey: process.env.HONUA_API_KEY,
});
const zarr = createZarrClient(client);

const registered = await zarr.register({
  layerId: 7,
  name: "Daily temperature",
  provider: "AwsS3",
  bucket: "coverage-data",
  rootPath: "temperature/daily.zarr",
});

const scanned = await zarr.refresh(registered.id);
// Supply the extent advertised by the associated layer/coverage metadata. The
// registration summary does not expose the scanned store extent itself.
const readiness = {
  storageExtent: [-180, -90, 180, 90] as const,
  tileMatrixSrid: 4326,
  variable: scanned.primaryVariable ?? undefined,
};
const status = zarr.assess(scanned, readiness);
if (status.serverTileHandoff !== "ready") {
  throw new Error(status.failures.map((failure) => failure.message).join("; "));
}

const tile = await zarr.tile({
  layerId: scanned.layerId,
  tileMatrixSetId: "WorldCRS84Quad",
  z: 3,
  x: 2,
  y: 4,
  variable: readiness.variable,
  datetime: "2026-08-13T00:00:00Z",
  maxResponseBytes: 2 * 1024 * 1024,
});

Contract and limits

• The client calls only /api/v1/admin/zarr-stores and /api/v1/datacubes/{layerId}/tiles/.... Alternate unversioned base paths are rejected, as are configured base paths containing traversal segments, control characters, percent encoding, query strings, fragments, or backslashes.
• Registration and metadata responses default to a 2 MiB ceiling. Tile responses also default to 2 MiB and can be reduced per request.
• Tile coordinates and optional elevation are non-negative integers. The server converts the advertised tile window into a bounded, chunk-aware read.
• A tile outside the coverage extent is returned as { status: 204, bytes: Uint8Array(0), contentType: null }; an intersecting tile is a 200 PNG.
• AbortSignal is forwarded to the shared request pipeline.
• assess() recognizes Zarr v2 little-endian numeric or boolean descriptors and the server-supported Zarr v3 named numeric or boolean data types. Codec readiness is version-specific: v2 permits uncompressed or zlib chunks, while v3 permits uncompressed or gzip chunks. Blosc, Zstandard, big-endian dtypes, and version-mismatched or ambiguous metadata fail explicitly. Server v3 metadata's canonical NumPy descriptor is normalized to the corresponding v3 name when a registration response enters the SDK.
• assess() mirrors the server's primary-or-first variable selection. Its readiness options require the requested tile matrix SRID and a finite, non-degenerate storage extent from the associated layer/coverage metadata, and accept an optional variable. Unrelated auxiliary variables do not block a valid raster. Tileable variables require every dimension to be non-empty, including x/lon and y/lat axes.
• Metadata must be refreshed and expose at least one variable before the tile handoff is considered ready.
• A positive storage SRID is required because the current tile handoff cannot reproject between the coverage and tile matrix set.

HonuaZarrClient does not fetch chunks from S3, Azure Blob Storage, or the local filesystem. assess().directObjectStoreRead therefore remains "unavailable". Server tile execution stays on the versioned Honua route.

openDirectZarrStore is a separate reader for reviewed Zarr v2 and v3 layouts on static HTTP or object storage. It sends bounded Range requests for known metadata keys and the chunks that intersect an explicit window. Credentials are omitted, redirects are not followed, and an unsupported codec or layout fails after metadata discovery and before chunk transfer. The API remains experimental until cross-deployment evidence is stable.

import { openDirectZarrStore } from "@honua/sdk-js/zarr";

const store = openDirectZarrStore({
  url: "https://data.example/temperature.zarr",
  limits: { maxChunks: 64, maxPixels: 1_048_576 },
});
const inspection = await store.inspect();
const samples = await store.readWindow({
  pixel: { x: 0, y: 0, width: 64, height: 64 },
  bands: [1],
});
void inspection;
void samples;