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 and
	// [Client.Stat] calls each have a separate four-slot lane. Each lane has a
	// bounded queue; calls fail with [ErrUnavailable] if it is full or the
	// wait times out.
	MaxConnections 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
	// 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. The directory must be owned by this user and must
	// not be writable by group or others. Without it, an existing socket
	// path is an error.
	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]. If the
	// object has changed, 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
}