object

Documentation

Overview

Package object defines an object-storage resource abstraction.

The API is intentionally S3-shaped (bucket/key, Put/Get/List/Delete, content checksums, conditional/idempotent puts) so out-of-tree adapters can map to S3, GCS, or Azure Blob without pulling cloud SDKs into ShiftLock core. This package is stdlib-only.

Index

• Constants
• Variables
• func ChecksumSHA256(body []byte) string
• func CopyReader(r io.Reader, max int) ([]byte, error)
• func SortMetas(metas []ObjectMeta)
• func ValidateKey(key string) error
• type Client
  • func NewClient(store Store, maxParallel int) *Client
  • func (c *Client) Delete(ctx context.Context, bucket, key string) error
  • func (c *Client) Get(ctx context.Context, bucket, key string, opts GetOptions) (ObjectMeta, []byte, error)
  • func (c *Client) List(ctx context.Context, bucket string, opts ListOptions) ([]ObjectMeta, error)
  • func (c *Client) Put(ctx context.Context, bucket, key string, body []byte, opts PutOptions) (ObjectMeta, error)
• type Config
• type GetOptions
• type ListOptions
• type ObjectMeta
• type PutOptions
• type Resource
  • func New(cfg Config) (*Resource, error)
  • func (r *Resource) Capabilities() resource.ResourceCapabilities
  • func (r *Resource) Client() *Client
  • func (r *Resource) Close() error
  • func (r *Resource) Describe() resource.Description
  • func (r *Resource) Health(ctx context.Context) resource.ResourceHealth
  • func (r *Resource) ID() resource.ResourceID
  • func (r *Resource) Kind() resource.Kind
  • func (r *Resource) Snapshot(ctx context.Context) (map[string]string, error)
  • func (r *Resource) Store() Store
• type Store

Constants

const DefaultMaxBytes = 4 << 20 // 4 MiB

DefaultMaxBytes is the per-object body size limit for memory adapters.

const DefaultMaxObjects = 4096

DefaultMaxObjects bounds in-memory stores.

const DefaultMaxParallel = 8

DefaultMaxParallel bounds concurrent Put/Get/List/Delete ops on a Client.

Variables

var (
	ErrInvalidArg    = errors.New("object: invalid argument")
	ErrNotFound      = errors.New("object: not found")
	ErrConflict      = errors.New("object: conflict")
	ErrChecksum      = errors.New("object: checksum mismatch")
	ErrBoundExceeded = errors.New("object: bound exceeded")
	ErrClosed        = errors.New("object: closed")
)

Functions

func ChecksumSHA256

func ChecksumSHA256(body []byte) string

ChecksumSHA256 returns hex-encoded sha256 of body.

func CopyReader

func CopyReader(r io.Reader, max int) ([]byte, error)

CopyReader drains r into a bounded buffer (helpers for adapters).

func SortMetas

func SortMetas(metas []ObjectMeta)

SortMetas sorts by bucket then key.

func ValidateKey

func ValidateKey(key string) error

ValidateKey rejects empty or path-escaping keys.

Types

type Client

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

Client wraps a Store with bounded concurrency.

func NewClient

func NewClient(store Store, maxParallel int) *Client

NewClient returns a concurrency-bounded Store façade.

func (*Client) Delete

func (c *Client) Delete(ctx context.Context, bucket, key string) error

func (*Client) Get

func (c *Client) Get(ctx context.Context, bucket, key string, opts GetOptions) (ObjectMeta, []byte, error)

func (*Client) List

func (c *Client) List(ctx context.Context, bucket string, opts ListOptions) ([]ObjectMeta, error)

func (*Client) Put

func (c *Client) Put(ctx context.Context, bucket, key string, body []byte, opts PutOptions) (ObjectMeta, error)

type Config

type Config struct {
	ID          resource.ResourceID
	DisplayName string
	Store       Store
	// MaxParallel bounds Client concurrency when wrapping Store.
	MaxParallel int
}

Config configures an object-store resource adapter.

type GetOptions

type GetOptions struct {
	// IfChecksum, when non-empty, requires the stored checksum to match.
	IfChecksum string
}

GetOptions controls a Get.

type ListOptions

type ListOptions struct {
	Prefix string
	// StartAfter is an exclusive key cursor (S3-shaped ContinuationToken lite).
	StartAfter string
	Limit      int
}

ListOptions filters a List.

type ObjectMeta

type ObjectMeta struct {
	Bucket      string            `json:"bucket"`
	Key         string            `json:"key"`
	Size        int64             `json:"size"`
	Checksum    string            `json:"checksum"` // sha256 hex
	ContentType string            `json:"content_type,omitempty"`
	UpdatedAt   time.Time         `json:"updated_at"`
	Attrs       map[string]string `json:"attrs,omitempty"`
	Generation  uint64            `json:"generation,omitempty"`
	Idempotency string            `json:"idempotency_key,omitempty"`
}

ObjectMeta is sanitized object metadata (no secret values).

type PutOptions

type PutOptions struct {
	ContentType    string
	Attrs          map[string]string
	IdempotencyKey string
	// IfChecksum, when non-empty, requires the existing object to match (CAS).
	IfChecksum string
	// IfNotExists refuses overwrite when the key already exists.
	IfNotExists bool
	// Checksum, when set, must match sha256(body); empty computes from body.
	Checksum string
}

PutOptions controls a Put.

S3-shaped notes (no AWS SDK):

• IdempotencyKey ≈ client token / dedupe key for retries
• IfChecksum / IfNotExists ≈ conditional put / If-None-Match
• Checksum is content integrity (sha256), analogous to checksum algorithms

type Resource

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

Resource is a fabric Resource over an object Store.

Capabilities: SupportsHealth + SupportsSnapshots only. SupportsFencing is false unless an adapter implements epoch advances on activate-manifest (this base adapter does not).

func New

func New(cfg Config) (*Resource, error)

New builds a Resource. Store is required.

func (*Resource) Capabilities

func (r *Resource) Capabilities() resource.ResourceCapabilities

func (*Resource) Client

func (r *Resource) Client() *Client

Client returns the bounded concurrency client.

func (*Resource) Close

func (r *Resource) Close() error

Close marks the resource closed for health probes.

func (*Resource) Describe

func (r *Resource) Describe() resource.Description

func (*Resource) Health

func (r *Resource) Health(ctx context.Context) resource.ResourceHealth

func (*Resource) ID

func (r *Resource) ID() resource.ResourceID

func (*Resource) Kind

func (r *Resource) Kind() resource.Kind

func (*Resource) Snapshot

func (r *Resource) Snapshot(ctx context.Context) (map[string]string, error)

Snapshot lists a sanitized object count (no bodies/secrets).

func (*Resource) Store

func (r *Resource) Store() Store

Store returns the underlying store.

type Store

type Store interface {
	Put(ctx context.Context, bucket, key string, body []byte, opts PutOptions) (ObjectMeta, error)
	Get(ctx context.Context, bucket, key string, opts GetOptions) (ObjectMeta, []byte, error)
	List(ctx context.Context, bucket string, opts ListOptions) ([]ObjectMeta, error)
	Delete(ctx context.Context, bucket, key string) error
}

Store is the object CRUD contract (bucket-scoped or flat namespace).