@voltro/plugin-storage 0.86.0 → 0.88.0

package/README.md

@@ -20,6 +20,18 @@ Installation, guides, the full API reference, and examples all live in the
 **[Voltro documentation](https://docs.voltro.dev/docs/intro/getting-started)** — the single source of truth. This README is
 deliberately short so there is nothing here to drift out of date.
 
+## Server helpers
+
+Import transport connectors and signed grant/upload-session helpers from
+`@voltro/plugin-storage/server` in server code. This entry uses the same
+implementations as the plugin root without loading the plugin registration graph. Browser descriptors use `@voltro/plugin-storage/rpc` and
+`@voltro/plugin-storage/errors`; the server entry is not browser-safe.
+
+Server-side operation coordination can observe a durable put with
+`makeStorageObjectMetadata(store).lookup(scope, claim)` without acquiring another
+claim or accessing provider bytes. See the Storage docs for pending/deleted
+states and the unverified execution status.
+
 ### Bounded HTTP source reader
 
 Server integrations may use `fetchIngestBody(url, maxBytes?, policy?)` to collect
@@ -68,6 +80,21 @@ Pass the returned `operationId` in a fresh authorized `storage.mintUploadTicket`
 
 Object keys are physical provider keys. Native operation-backed writes use their existing content-addressed namespace; use the reference ID and approved ticket binding instead of inferring authority from a logical path inside a physical key.
 
+## Observe a durable operation from trusted server code
+
+`StorageService.operationStatus({ operationId, tenantId })` reads the exact original put identity in the selected service's configured instance, actual reference catalogue, physical namespace and logical bucket. Supply the tenant explicitly, including `null` for a global operation. Every result includes an opaque `scope` identifying that destination; recovery code must compare it with its retained scope.
+
+The states are `absent`, `reserved`, `ready`, `deleting` and `deleted`. Only `ready` includes a matching readable `ref`. Unsupported, unbound, inconsistent or unavailable metadata fails with `StorageError`; it never becomes `absent`. The observation does not reserve, put, claim, delete, read provider bytes or retry a provider operation. Existing operation IDs and tables do not change.
+
+Authorize the business operation before using this trusted server API. It is not a client RPC or access-policy check. Absence is an observation of this metadata view, not proof that an earlier provider request did nothing. Readiness does not prove current provider bytes, continued liveness or application-level artifact validity. Verify those separately, and keep the original operation identity when the outcome is uncertain. Custom `StorageServiceShape` implementations must add this method or return a typed unsupported `StorageError`; the standard service implements it.
+
+## HTTPS-only source reads
+
+`IngestPolicy.requireHttps: true` requires HTTPS at the initial URL and every
+redirect before fetching. Host allowlisting does not bypass it. The default is
+false. This applies to `fetchIngestBody` and configured URL ingestion while
+preserving the existing byte, redirect, address and cancellation boundaries.
+
 ## Signed token deadlines
 
 Native signed read grants and upload, finalize, resumable and multipart tickets expire at their signed Unix-second deadline. Verification refuses the exact deadline and every later instant; a zero-second lifetime grants no usable interval. Obtain a new token through the authorized issuer when another transfer or read is needed.