ExternalRef

Defined in: src/external.ts:364

A reference to an already-published unary result.

A unary handler may return an ExternalRef in place of its result values. The server then answers with the external-location pointer batch for url directly: the result is not built or validated, nothing is serialized, compressed or uploaded during the call, and the ref is used whether or not the server has external storage configured and regardless of externalizeThresholdBytes (a ref is never inlined). It does not count toward maxExternalizedResponseBytes. Clients resolve it like any other pointer, so they need no change. Unary methods only.

Build one with publishExternal (or by hand for an object published out of band). The object at url must be an Arrow IPC stream (optionally Content-Encoding: zstd) whose schema is the method’s result schema and which holds exactly one 1-row data batch.

The caller owns caching the ref and the object’s lifecycle: a long-lived ref must not point at an object under the short-TTL lifecycle rule used for per-call uploads, and a pre-signed URL expires – re-sign or rebuild the ref before then. Only return a ref to callers who are all entitled to the same content.

Example

let cached: ExternalRef | undefined;
protocol.unary("catalog", {
  params: {},
  result: { result: str },
  handler: async () => {
    cached ??= await publishExternalResult(catalogSchema, { result: buildCatalog() }, storage);
    return cached;
  },
});

Constructors

Constructor

new ExternalRef(url, sha256?): ExternalRef;

Defined in: src/external.ts:383

Parameters

Parameter	Type	Description
url	string	Where the published IPC stream lives; must be non-empty.
sha256?	string | null	Optional lowercase hex SHA-256 (64 characters) of the raw IPC stream bytes. null/undefined means no digest.

Returns

ExternalRef

Throws

Error if url is empty or sha256 is not 64 lowercase hex characters.

Properties

sha256

readonly sha256: string | undefined;

Defined in: src/external.ts:373

Lowercase hex SHA-256 of the raw (pre-compression) IPC stream bytes, sent as vgi_rpc.location.sha256. undefined omits the key, so clients skip the content check – use this for an object rewritten in place or one too large to hash.

---

url

readonly url: string;

Defined in: src/external.ts:366

Where the published IPC stream lives.

Methods

pointerBatch()

pointerBatch(schema): VgiBatch;

Defined in: src/external.ts:397

Build the zero-row pointer batch announcing this ref against schema (the method’s result schema).

Parameters

Parameter	Type
schema	VgiSchema

Returns

VgiBatch