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 [Client.Warm] 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 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 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 WarmOptions struct {
	// ETag pins warming to this strong entity tag. An unavailable version fails
	// with [ErrVersionMismatch].
	ETag string
}

type WarmResult struct {
	Metadata Metadata
	// RetainUntil is the accepted deadline. Zero means retention was refused.
	// Acceptance does not mean that all pages have finished loading.
	RetainUntil time.Time
}