feat(blob): add bounded HTTP delivery

[aaltshuler]

Summary

• add authenticated graph-level GET and explicit HEAD /graphs/{graph_id}/blob over the engine-owned Blob read facade
• support strong If-Match, weak If-None-Match, strong If-Range, one byte range, and exact 304/412/416 semantics
• stream managed content in ordered 4 MiB reads with a two-chunk / 8 MiB retained-payload ceiling and ownership-driven cancellation
• redirect only whole-object external descriptors with zero target-object I/O; ranged external descriptors fail loudly instead of widening
• preserve exact branch/snapshot identity, redact physical storage details, and publish the selector/error DTOs and generated OpenAPI contract
• add deterministic transport, route, authorization, conditional, range, backpressure, cancellation, and external-reference coverage

This is RFC-033 Phase 2A, rebased directly onto main after #480 and #481. It adds no Blob mutation API, CLI surface, recovery-protocol change, manifest-schema bump, or Lance data-format bump. Shared API/error initializers changed only to compose the additive Blob wire contract with the existing graph-commit precondition contract.

Validation

• cargo fmt --all --check
• git diff --check
• scripts/check-agents-md.sh
• cargo test -p omnigraph-server --locked --lib blob_transport::tests
• cargo test -p omnigraph-server --locked --test data_routes
• cargo test -p omnigraph-server --locked --test auth_policy
• cargo test -p omnigraph-server --locked --test openapi
• cargo test -p omnigraph-engine --test branching branch_merge_with_blob_columns_preserves_blob_data -- --exact --nocapture
• cargo test -p omnigraph-engine --test branching blob_snapshot_inherited_from_main_refuses_named_branch_recreation_aba -- --exact --nocapture
• cargo test -p omnigraph-engine --features failpoints --test failpoints blob_live_branch_read_refuses_delete_recreate_aba_after_capture -- --exact --nocapture
• cargo test --workspace --locked --features omnigraph-engine/failpoints,omnigraph-cluster/failpoints
• cargo clippy --workspace --all-targets --locked -- -D warnings -W clippy::dbg_macro
• cargo clippy --workspace --all-targets --locked --features omnigraph-engine/failpoints,omnigraph-cluster/failpoints -- -D warnings -W clippy::dbg_macro
• cargo test -p omnigraph-server --features aws --locked

Two independent final reviews of the rebased candidate reported no findings.

Greptile Summary

The PR adds graph-level bounded Blob delivery over explicit GET and HEAD routes.

• Implements managed-content streaming with conditional and single-range HTTP semantics.
• Redirects whole-object external Blob descriptors while refusing descriptors that cannot be represented safely.
• Reuses read authorization and snapshot resolution across query and Blob routes.
• Publishes shared selector/error DTOs, OpenAPI output, documentation, and route/auth/transport tests.
• Tightens RustFS readiness checks, serializes configured S3 tests, and improves failure diagnostics.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
crates/omnigraph-server/src/blob_transport.rs	Adds conditional, range-aware, ownership-cancelled Blob delivery with a two-chunk retained-payload bound.
crates/omnigraph-server/src/handlers.rs	Adds explicit Blob GET/HEAD handlers and centralizes branch-or-snapshot read authorization.
crates/omnigraph-server/src/lib.rs	Registers the Blob route and OpenAPI surface while extending structured API errors for HTTP range failures.
crates/omnigraph-api-types/src/lib.rs	Adds additive Blob selector and normalized range-error DTOs.
.github/workflows/ci.yml	Makes RustFS readiness failure explicit, serializes the configured integration suite, and adds redacted diagnostics.

Sequence Diagram

sequenceDiagram
    participant Client
    participant Auth as Auth middleware
    participant Handler as Blob handler
    participant Policy as Read authorization
    participant Engine as Blob read facade
    participant Transport as Bounded HTTP transport
    Client->>Auth: "GET/HEAD /graphs/{id}/blob"
    Auth->>Handler: Resolved actor and graph
    Handler->>Policy: Authorize resolved branch/snapshot
    Policy-->>Handler: Allow
    Handler->>Engine: read_blob_at(target, cell)
    Engine-->>Handler: Managed reader or external descriptor
    Handler->>Transport: Apply validators/range semantics
    alt Managed Blob
        Transport-->>Client: 200/206/304/412/416
    else Whole external Blob
        Transport-->>Client: 302 redirect, no-store
    else Ranged external descriptor
        Transport-->>Client: Redacted 500 refusal
    end

Loading

_{Reviews (2): Last reviewed commit: "feat(blob): add bounded HTTP delivery" | Re-trigger Greptile}

Context used (3)

• Knowledge Base — Server Request Handling
• Knowledge Base — CLI and Config
• Knowledge Base — Dev conventions and invariants