Documentation Edit this page

Blobstore

Binary large object storage service. Provides a centralized API for storing and retrieving binary data blobs used by other services in the platform.

Architecture

                  +---------------------------+
                  |         Clients           |
                  +---------------------------+
                        |             |
                  HTTPS |             | url://
                        v             v
          +------------------+ +------------------------+
          | blobstore-server | | blobstore-service-     |
          |      .jar        | |     server.jar         |
          | (Cloud Run)      | | (ContainerNursery)     |
          +------------------+ +------------------------+
                        |             |
                        v             v
                  +---------------------------+
                  |     Blobstore Backend     |
                  +---------------------------+
                              |
                              v
                  +---------------------------+
                  |     Blob Storage Layer    |
                  +---------------------------+

Deployment

• Cloud Run: blobstore-server.jar deployed to Google Cloud Run, serving HTTPS traffic at api.blobstore.wasmserver.com.
• ContainerNursery: blobstore-service-server.jar deployed to ContainerNursery, accessible via the url://blobstore/ protocol.

Health Checks

• HTTPS endpoint: https://api.blobstore.wasmserver.com/
• ContainerNursery: monitored via standard ContainerNursery health checks
• ProductionHealth check — BlobstoreHealthCheck (community.kotlin.healthchecks.blobstore:blobstore-health-check), registered with the ProductionHealthService, runs a full end-to-end verification over url://blobstore/: health endpoint, upload, blobExists, download-with-content-verification, listing, and cleanup. It additionally exercises multi-chunk reassembly (a blob spanning several 4 MB chunks) and reads a permanently-pinned canary blob (plus an optional known production blob) back on every run, verifying it still hashes to its content address — so any regression that would make already-stored blobs unreadable (a chunk-reassembly, integrity, or read-path break) surfaces as a red check rather than silent data loss.

Data Durability

• This service holds critically important production data. Blobs are content-addressed and write-once, so everything already stored must remain byte-for-byte readable indefinitely; preserving read/write access to existing blobs is the top operational priority, and avoiding data loss overrides other changes.
• The on-storage format is a frozen backward-compatibility contract — the SHA-256 uppercase-hex content address, the blobs/{HASH} S3 key derivation, the pins(owner, file) ownership metadata, and the chunk-reassembly path. See Data durability and backward compatibility for the full contract.
• The deployed blobstore-service-server.jar pins its storage-affecting dependencies (the AWS S3 client, hashing, and metadata-schema access) so the on-storage format cannot drift underneath already-stored blobs. Any change to those pins is a deliberate data-migration decision, verified against the health check's canary read-back before deployment.

Notes

• Standard layered architecture with public HTTPS API and internal ContainerNursery service endpoint.
• See the Blobstore project overview for the full component breakdown and design decisions.