racersdk

type Client struct {
	// contains filtered or unexported fields
}

type ClientConfig struct {
	// Cache names the Racer cache, a DNS subdomain such as "blobs". The
	// client connects to /run/racer/<Cache>/client/socket.
	Cache string
	// MaxConnections bounds concurrent [Client.Get] transfers without
	// [ReadOptions.SmallObject]. Zero means 64. SmallObject transfers have a
	// separate four-slot lane. [Client.Stat] and the prefetch calls share another
	// lane with MaxConnections slots, so every transfer can be preceded by a
	// Stat. Each lane has a bounded queue; calls fail with [ErrUnavailable] if
	// it is full or the wait times out.
	MaxConnections int
	// PageCredits is how many pages Racer may send ahead of the reader on
	// each [Client.Get]. Racer's fetch window for a read is the smaller of
	// this and its RACER_RANGE_WINDOW_PAGES, so it bounds single-read
	// throughput. Zero means 2; the maximum is 64. Each credit lets Racer hold
	// one more 16 MiB page for the read.
	PageCredits int
}

type HostReadOptions struct {
	// Offset is the first object byte to read.
	Offset int64
	// Length is the number of bytes to read. Zero reads to the end of the
	// object.
	Length int64
	// ETag pins the read to one version, as in [ReadOptions].
	ETag string
	// DestinationOffset is the file offset of the first byte written.
	DestinationOffset int64
	// DestinationLength bounds the file window Racer may write, starting at
	// DestinationOffset. It must be at least the range length. Zero means
	// the file size minus DestinationOffset.
	DestinationLength int64
	// OnPage, if set, is called after Racer reports that a page is in the
	// file, with the object offset and length of the bytes written. It runs
	// on the calling goroutine and should be quick.
	OnPage func(offset, length int64)
}

type HostReadResult struct {
	// Metadata describes the version that was read.
	Metadata Metadata
	// Offset and Length are the object range that was written.
	Offset, Length int64
}

type Key [32]byte

type Metadata struct {
	// Size is the object length in bytes.
	Size int64
	// ETag is a strong HTTP entity tag such as "\"v1\"". Racer uses it to
	// ensure every page of a read comes from the same version.
	ETag string
	// ContentType is optional.
	ContentType string
	// ExpiresAt is when Racer must stop serving this version from cache. It
	// is required and kept at millisecond precision.
	ExpiresAt time.Time
}

type Object struct {
	// contains filtered or unexported fields
}

type Origin func(ctx context.Context, request OriginRequest) (Metadata, io.ReadCloser, error)

type OriginConfig struct {
	// Cache names the Racer cache. The origin listens on
	// /run/racer/<Cache>/origin/socket. The directory must already exist and
	// its ancestors must not be symlinks.
	Cache string
	// CacheUID optionally binds the origin to one ClusterCache UID. Origin
	// sockets are named by cache name, so a ClusterCache that is deleted and
	// recreated under the same name reuses the path while an origin for the
	// old UID may still be listening. When CacheUID is set, requests whose
	// Racer-Cache header names a different or no UID get 503 Service
	// Unavailable instead of being served. Empty accepts any cache UID.
	CacheUID string
	// MaxConcurrentRequests bounds concurrent content requests; Racer receives
	// a retryable error beyond it. Zero means 64. Metadata requests have a
	// small separate limit.
	MaxConcurrentRequests int
	// RecoverStaleSocket lets ServeOrigin replace a socket left behind by an
	// earlier ServeOrigin with this option that exited without cleanup, such
	// as after a crash or SIGKILL. Enable it when a supervisor restarts the
	// origin. The directory must be owned by this process's effective user
	// and must not be writable by group or others. ServeOrigin keeps
	// .racer-origin.lock and .racer-origin.socket in the directory to
	// recognize its own sockets, and it never replaces a socket that is
	// still accepting connections or that it did not create with this
	// option. Turning the option on after a crash with it off therefore
	// does not remove the old socket.
	//
	// Without it, an existing socket path is an error. ServeOrigin removes
	// its socket only when it returns, so if the process exits without
	// returning, later calls fail until the socket is removed by hand or by
	// a startup step that knows no other origin is serving.
	RecoverStaleSocket bool
}

type OriginRequest struct {
	Request
	// Head asks for metadata only.
	Head bool
	// ETag, when set, is the only version that may be served.
	ETag string
	// Offset is the first byte to return. It is always a multiple of
	// [PageSize].
	Offset int64
	// Length is the maximum number of bytes to return, at most [PageSize].
	// The range may extend past the end of the object.
	Length int64
}

type PrefetchBytes struct {
	LogicalRequested  int64
	AlignedRequested  int64
	AlreadyResident   int64
	Queued            int64
	InFlight          int64
	Joined            int64
	FetchedFromOrigin int64
	Admitted          int64
	Failed            int64
}

type PrefetchCoverage struct {
	ResidentBytes int64
	ObservedAt    time.Time
}

type PrefetchError struct {
	// Status is the HTTP status code.
	Status int
	// Code is the machine-readable code, for example "stale_sequence". It
	// is empty if the response had no valid error body.
	Code string
	// Message is human-readable text with no stable contract.
	Message string
	// RetryAfter is the server's Retry-After, if any.
	RetryAfter time.Duration
}

type PrefetchPart struct {
	ID   string
	Spec PrefetchSpec
}

type PrefetchRef struct {
	// Key is the object key as 64 lowercase hexadecimal characters.
	Key string
	// ETag optionally pins a version. Empty resolves the current version once
	// at submit.
	ETag string
	// Offset is the first byte. It must be less than the object length.
	Offset int64
	// Length is the number of bytes. Zero means to the end of the object.
	Length int64
	// Metadata is passed to the origin like [Request.Metadata].
	Metadata string
}

type PrefetchRefStatus struct {
	// Index is the ref position in the submitted spec.
	Index int
	Key   string
	// ETag is the resolved version, empty if resolution failed.
	ETag   string
	Offset int64
	Length int64
	// Outcome is "succeeded", "failed", or "pending".
	Outcome string
	// Error is set for failed refs, for example "version_changed".
	Error string
}

type PrefetchSpec struct {
	// CacheUID, if set, must equal the live ClusterCache UID.
	CacheUID string
	// Priority is "high", "normal", or "low". Empty means "normal".
	Priority string
	// Generation and Sequence order updates of one ticket; see
	// [PrefetchWindow]. Each is at most 2^53-1.
	Generation uint64
	Sequence   uint64
	// TTL is how long the ticket lives without an update. It is rounded up to
	// whole seconds. Zero means the server default (600s); Racer caps it.
	TTL time.Duration
	// MaxPendingBytes bounds queued and in-flight bytes for the ticket. Zero
	// means the server default.
	MaxPendingBytes int64
	// Authorization is passed to the origin for every ref, like
	// [Request.Authorization]. Racer keeps it in memory only.
	Authorization string
	// Refs lists the ranges to prefetch. It must not be empty.
	Refs []PrefetchRef
}

type PrefetchState string

type PrefetchStatus struct {
	ID       string
	CacheUID string
	State    PrefetchState
	// Reason is set only for canceled tickets: "client", "expired",
	// "superseded", "cache_removed", or "passthrough".
	Reason     string
	Priority   string
	Generation uint64
	Sequence   uint64
	// Settled reports that nothing for the current window is queued or in
	// flight. Success means pages were admitted, not that they stay resident.
	Settled       bool
	TTL           time.Duration
	ExpiresAt     time.Time
	CreatedAt     time.Time
	UpdatedAt     time.Time
	RefsTotal     int64
	RefsSucceeded int64
	RefsFailed    int64
	RefsPending   int64
	Bytes         PrefetchBytes
	// Coverage is set only when requested.
	Coverage *PrefetchCoverage
	// Refs is set only when requested; continue with NextCursor.
	Refs       []PrefetchRefStatus
	NextCursor string
	// Created reports that [Client.Prefetch] created the ticket (HTTP 201).
	Created bool
}

type PrefetchWindow struct {
	// contains filtered or unexported fields
}

type ReadOptions struct {
	// Offset is the first byte to read.
	Offset int64
	// Length is the number of bytes to read. Zero reads to the end of the
	// object. A range that extends past the end fails with
	// [ErrRangeNotSatisfiable].
	Length int64
	// ETag pins the read to one version, typically from [Client.Stat]. Use it
	// when several reads of a key must see the same bytes, since separate
	// unpinned reads may see different versions. If that version is no
	// longer available, Get fails with [ErrVersionMismatch].
	ETag string
	// SmallObject declares that the object is at most [PageSize] bytes. Small
	// reads use a separate admission queue so they are not delayed behind
	// large transfers. Get fails with [ErrInvalidRequest] if the object is
	// larger.
	SmallObject bool
}

type Request struct {
	Key Key
	// Metadata tells the origin how to locate the object, for example a bucket
	// and path. Racer does not interpret it.
	Metadata string
	// Authorization is a credential for the origin. Racer does not interpret it.
	Authorization string
}

type StatusOptions struct {
	// Wait blocks until the ticket settles or Wait elapses, whichever is
	// first. Racer caps it (default 60s) and rejects larger values.
	Wait time.Duration
	// Coverage probes owners for resident bytes of the desired set.
	Coverage bool
	// Refs is "", "failed", or "all" and selects per-ref outcomes.
	Refs string
	// Cursor continues a previous page of refs from
	// [PrefetchStatus.NextCursor].
	Cursor string
}