ctlproto

type AssociateRequest ¶

type AssociateRequest struct {
	Domain       string            `json:"domain"`
	Associations []PackAssociation `json:"associations"`
}

AssociateRequest records that each context references each pack, so reclamation can later scope itself to an owner without walking the store. A filesystem node issues this on its write path; only the association WRITE crosses the wire, because reclamation needs the durable index and the blob store together and therefore runs blobgw-side.

type AssociateResponse ¶

type AssociateResponse struct {
	Error        string `json:"error,omitempty"`
	Obliterating bool   `json:"obliterating,omitempty"`
}

AssociateResponse is returned after an Associate RPC. Error is non-empty on failure. Obliterating is set when the batch was refused because a named pack is being reclaimed — the caller must treat its write as failed and retry, which is distinct from a transport or backend error.

type ChunkLocation ¶

type ChunkLocation struct {
	ChunkHash string  `json:"chunk_hash"`
	PackRef   PackRef `json:"pack_ref"`
}

ChunkLocation pairs a chunk's content hash with its PackRef. It is the unit a RecordRequest conveys — one entry per chunk that has been packed and uploaded, mirroring the pack_manifest(domain, chunk_hash, pack_hash, offset, length) row.

type Codec ¶

type Codec interface {
	Marshal(v any) ([]byte, error)
	Unmarshal(data []byte, v any) error
}

Codec is the swappable serialisation interface for control-plane messages. The committed target format is protobuf (see controlplane.proto and ADR-001 §2.5). JSONCodec is the default until protoc-gen-go is in the build chain.

var DefaultCodec Codec = JSONCodec{}

type JSONCodec ¶

type JSONCodec struct{}

JSONCodec marshals/unmarshals using encoding/json. It is the interim default pending the protobuf migration; see the package doc.

func (JSONCodec) Marshal(v any) ([]byte, error)

func (JSONCodec) Unmarshal(data []byte, v any) error

type LookupBatchRequest ¶

type LookupBatchRequest struct {
	Domain      string   `json:"domain"`
	ChunkHashes []string `json:"chunk_hashes"`
}

LookupBatchRequest asks blobgw to resolve a batch of chunk hashes to their pack locations within Domain. Chunk hashes not present in the index are simply absent from the response map (they are novel chunks that the caller must pack and upload).

Batch size: callers MUST split slices longer than MaxChunkHashesPerBatch across multiple requests to stay within the NATS 1 MB payload limit.

type LookupBatchResponse ¶

type LookupBatchResponse struct {
	Locations map[string]PackRef `json:"locations"`
	Error     string             `json:"error,omitempty"`
}

LookupBatchResponse carries the resolved chunk locations. Locations contains only the hashes that were found in the index. Error is non-empty when the server encountered a fatal error; on error, Locations may be nil or partial.

type ObliterateContextRequest ¶

type ObliterateContextRequest struct {
	Domain  string `json:"domain"`
	Context string `json:"context"`
}

ObliterateContextRequest asks blobgw to reclaim the bytes an owner context held, using the mark-based sequence. The node cannot do this itself: it needs the durable association index and blob deletion authority at once.

type ObliterateContextResponse ¶

type ObliterateContextResponse struct {
	Error                string `json:"error,omitempty"`
	PacksConsidered      int    `json:"packs_considered,omitempty"`
	PacksReclaimed       int    `json:"packs_reclaimed,omitempty"`
	PacksStillReferenced int    `json:"packs_still_referenced,omitempty"`
	PacksHeldByOther     int    `json:"packs_held_by_other,omitempty"`
	PacksSkippedError    int    `json:"packs_skipped_error,omitempty"`
	BytesReclaimed       int64  `json:"bytes_reclaimed,omitempty"`
}

ObliterateContextResponse reports what a reclamation pass did. The counters mirror snapshot.ReclaimResult so an operator sees the same numbers on both sides of the wire.

type PackAssociation ¶

type PackAssociation struct {
	PackHash string `json:"pack_hash"`
	Context  string `json:"context"`
}

PackAssociation binds one pack to one owning context. It mirrors snapshot.PackAssociation on the wire.

type PackRef ¶

type PackRef struct {
	PackHash string `json:"pack_hash"`
	Offset   int64  `json:"offset"`
	Size     int64  `json:"size"`
}

PackRef locates a content-addressed chunk within a pack blob. It is the value half of the dedup mapping (chunk hash → where the chunk physically lives in the object store). The blobgw server maps this to and from snapshot.PackRef; the mlfs client maps it to its own local representation.

type PresignBatchRequest ¶

type PresignBatchRequest struct {
	Domain     string    `json:"domain"`
	Op         PresignOp `json:"op"`
	Keys       []string  `json:"keys"`
	TTLSeconds int32     `json:"ttl_seconds"`
}

PresignBatchRequest asks blobgw to mint a batch of presigned S3 URLs for the given object keys within Domain. Op selects GET (read) or PUT (write). TTLSeconds is the requested validity duration; blobgw may cap it based on the credential impl (e.g. AWS STS session limit — see ADR-001 §2.9).

Batch size: callers MUST split slices longer than MaxPresignKeysPerBatch across multiple requests to stay within the NATS 1 MB payload limit.

type PresignBatchResponse ¶

type PresignBatchResponse struct {
	URLs          map[string]string `json:"urls"`
	ExpiresAtUnix int64             `json:"expires_at_unix"`
	Error         string            `json:"error,omitempty"`
}

PresignBatchResponse carries the minted presigned URLs. URLs maps each requested key to its presigned URL. ExpiresAtUnix is the Unix timestamp (seconds) at which all URLs in this batch expire; the node should schedule a refresh before this time (refresh-on-expiry is required by the AWS STS impl — see ADR-001 §2.9). Error is non-empty on failure.

type PresignOp ¶

type PresignOp string

PresignOp is the HTTP verb a presigned URL will be valid for.

Codec migration note: the current JSONCodec encodes PresignOp as its string value ("GET" or "PUT"). The .proto definition declares PresignOp as an enum (GET=1, PUT=2); switching to a ProtobufCodec changes the wire representation from the string name to an integer. A rolling upgrade requires all nodes to adopt the new codec simultaneously, or the proto enum must be annotated to preserve string-name encoding (e.g. via protojson or a custom codec). Plan the codec migration as a coordinated cutover, not a gradual rollout, to avoid mixed-codec clusters misrouting presign requests.

const (
	// PresignGet mints a presigned URL that authorises a GET (read) of the
	// object. Used by mlfs nodes fetching pack blobs from the tenant S3 bucket.
	PresignGet PresignOp = "GET"

	// PresignPut mints a presigned URL that authorises a PUT (write) of the
	// object. Used by mlfs nodes uploading newly assembled pack blobs.
	PresignPut PresignOp = "PUT"
)

type PurgePacksRequest ¶

type PurgePacksRequest struct {
	Domain     string   `json:"domain"`
	PackHashes []string `json:"pack_hashes"`
}

PurgePacksRequest asks blobgw to remove every index entry in Domain that points to one of the given pack hashes. GC calls this after it reclaims a pack blob so the index never hands out a reference to collected bytes. Purging an absent pack is a no-op (idempotent).

type PurgePacksResponse ¶

type PurgePacksResponse struct {
	Error string `json:"error,omitempty"`
}

PurgePacksResponse is returned by blobgw after a PurgePacks RPC. Error is non-empty on failure.

type RecordRequest ¶

type RecordRequest struct {
	Domain    string          `json:"domain"`
	Locations []ChunkLocation `json:"locations"`
}

RecordRequest asks blobgw to persist a batch of chunk locations in Domain. This is called after pack blobs have been durably uploaded to S3 (ADR-001 §4 invariant I1: durability before pointer). Recording is idempotent — first-writer-wins at the chunk_hash primary key.

Batch size: callers MUST split slices longer than MaxChunkHashesPerBatch across multiple requests.

type RecordResponse ¶

type RecordResponse struct {
	Error string `json:"error,omitempty"`
}

RecordResponse is returned by blobgw after a Record RPC. Error is non-empty on failure.