G3N Retail Stack Story

Appearance

MRS - Metarecord Service ​

MRS is the stack's content storage service. It exists for payloads that are too large or too flexible to live inside transactional records. Instead of embedding large files into business records, MRS stores them separately and provides a stable metadata layer to find and manage them.

MRS keeps the contract simple. You create records with metadata, attach content either inline (for small JSON) or by presigned upload (for larger payloads), and read or list those records later.

Service scope and boundaries ​

MRS owns large or flexible content and its metadata. It does not replace PVM or PMC records, and it is not a general search engine. Its role is to keep heavy payloads separate while still making metadata searchable and auditable.

Implemented feature breakdown (what exists today) ​

  • Inline JSON records: Store small JSON payloads directly inside the record.
  • Presigned upload flow: Create a record, upload large content, and complete the record.
  • Metadata retrieval: Get, meta, and head access patterns for records.
  • Listing and search: List records by metadata and tags with pagination.
  • Tags: Add and remove tags to organize content.
  • TTL and doom: Set expiry and terminal doom states.
  • Strict upload constraints: Content MD5 required, gzip required for large uploads, size caps enforced.

How the features are implemented (behavioral breakdown) ​

Inline JSON flow

  1. A record is created with metadata, a small JSON payload, and content MD5.
  2. The content is stored inline and returned directly in responses.
  3. The record is discoverable through metadata and tag-based list queries.

Presigned upload flow

  1. A record is created in a pending state with metadata and content MD5.
  2. A presigned upload URL is issued.
  3. The client uploads a gzipped payload directly to storage.
  4. The record is completed so it becomes visible for list and read operations.

Tags and TTL

  • Tags can be added or removed to group related content.
  • TTL can be set so records expire automatically.
  • Doomed is terminal and prevents further mutations.

Example use cases (extensive) ​

Publish artifacts storage: A publishing flow generates a large manifest or content pack. The artifacts are stored in MRS with metadata that points back to the publish run. PMC references the record without embedding the payload.

Operational configuration: A team stores a large configuration file or dataset that must be shared across services. MRS keeps it in a stable, auditable record that can be versioned by creating a new record when changes are made.

Audit and collaboration: A product team stores large JSON snapshots or reports, tags them by campaign or season, and uses TTL to automatically retire old versions.

Media and asset storage: A merchandising team stores large media or assets that need stable references without inflating transactional records. MRS provides metadata and controlled access through presigned URLs.

Example scenarios and acceptance criteria ​

Scenario 1: Inline JSON record ​

  • A small JSON payload is stored with metadata.
  • The record is retrieved and listed by metadata filters.
  • Acceptance: the payload is returned inline; metadata and tags are searchable.

Scenario 2: Presigned upload with MD5 and gzip ​

  • A large payload is created with a pending record and presigned URL.
  • The client uploads a gzipped payload with a matching MD5 and completes the record.
  • Acceptance: the record becomes visible after completion; MD5 and gzip requirements are enforced.

Scenario 3: TTL expiry and doom ​

  • A record is created with TTL and later marked doomed.
  • A subsequent mutation is attempted.
  • Acceptance: doomed is terminal; TTL expiry removes or hides the record per policy.

Scenario 4: Tag-driven listing ​

  • Tags are added to group a set of records.
  • A list call filters by tag and container.
  • Acceptance: results include only matching records with pagination tokens.

Constraints and invariants ​

  • MRS is not a general-purpose search engine; it focuses on metadata and tags.
  • Large uploads must be gzipped, include content MD5, and are capped in size.
  • Records can be doomed and expired; doomed is terminal.
  • Container names are expected to be stable and predictable so listing and reporting remain consistent.

How MRS fits with other services ​

USM sessions authenticate calls into MRS, and OFM membership gating ensures org-scoped access is enforced. PVM and PMC can reference MRS records when large payloads are needed, but those services do not embed MRS content directly into their own records.

Implemented vs planned ​

Implemented: inline JSON records, presigned upload and download flows, tags, TTL, and metadata-first listing.

Planned: no additional public contract features are defined at this time. Any future changes will be additive and documented explicitly.

For exact request and response shapes, see the MRS contract pages at https://doc.g3nretailstack.com/mrs/.