batch

package
v0.2.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package batch provides persistence for OpenAI-compatible batch lifecycle endpoints.

Index

Constants

View Source
const (
	// RequestIDMetadataKey is the legacy metadata key used to persist batch request IDs.
	RequestIDMetadataKey = "request_id"
	// UsageLoggedAtMetadataKey is the legacy metadata key used to mark logged batch usage.
	UsageLoggedAtMetadataKey = "usage_logged_at"
)

Variables

View Source
var ErrNotFound = errors.New("batch not found")

ErrNotFound indicates a requested batch was not found.

Functions

This section is empty.

Types

type MemoryStore

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

MemoryStore keeps batches in process memory. Data survives across requests but not process restarts.

func NewMemoryStore

func NewMemoryStore() *MemoryStore

NewMemoryStore creates an empty in-memory batch store.

func (*MemoryStore) ClaimUsage added in v0.2.4

func (s *MemoryStore) ClaimUsage(_ context.Context, id string, now time.Time, timeout time.Duration) (UsageClaim, error)

ClaimUsage grants the batch's usage claim unless its usage is logged or a claim younger than timeout is held.

func (*MemoryStore) Close

func (s *MemoryStore) Close() error

Close releases resources (no-op for memory store).

func (*MemoryStore) CompleteUsage added in v0.2.4

func (s *MemoryStore) CompleteUsage(_ context.Context, id string, loggedAt time.Time) error

CompleteUsage marks the batch's usage as logged and releases the claim.

func (*MemoryStore) Create

func (s *MemoryStore) Create(_ context.Context, batch *StoredBatch) error

Create stores a new batch.

func (*MemoryStore) Delete added in v0.1.53

func (s *MemoryStore) Delete(_ context.Context, id string) error

Delete removes a stored batch object.

func (*MemoryStore) Get

func (s *MemoryStore) Get(_ context.Context, id string) (*StoredBatch, error)

Get retrieves one batch by id.

func (*MemoryStore) List

func (s *MemoryStore) List(_ context.Context, limit int, after, userPath string) ([]*StoredBatch, error)

List returns batches ordered by created_at desc, id desc.

func (*MemoryStore) Update

func (s *MemoryStore) Update(_ context.Context, batch *StoredBatch) error

Update replaces an existing batch object, keeping its usage marker.

type MongoDBStore

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

MongoDBStore stores batches in MongoDB.

func NewMongoDBStore

func NewMongoDBStore(database *mongo.Database) (*MongoDBStore, error)

NewMongoDBStore creates collection indexes if needed.

func (*MongoDBStore) ClaimUsage added in v0.2.4

func (s *MongoDBStore) ClaimUsage(ctx context.Context, id string, now time.Time, timeout time.Duration) (UsageClaim, error)

ClaimUsage grants the batch's usage claim with one conditional update, so concurrent callers cannot both take it.

func (*MongoDBStore) Close

func (s *MongoDBStore) Close() error

Close is a no-op; Mongo client lifecycle is managed by storage layer.

func (*MongoDBStore) CompleteUsage added in v0.2.4

func (s *MongoDBStore) CompleteUsage(ctx context.Context, id string, loggedAt time.Time) error

CompleteUsage marks the batch's usage as logged and releases the claim.

func (*MongoDBStore) Create

func (s *MongoDBStore) Create(ctx context.Context, batch *StoredBatch) error

Create inserts a new batch.

func (*MongoDBStore) Delete added in v0.1.53

func (s *MongoDBStore) Delete(ctx context.Context, id string) error

Delete removes a stored batch object.

func (*MongoDBStore) Get

func (s *MongoDBStore) Get(ctx context.Context, id string) (*StoredBatch, error)

Get returns a batch by id.

func (*MongoDBStore) List

func (s *MongoDBStore) List(ctx context.Context, limit int, after, userPath string) ([]*StoredBatch, error)

List returns batches ordered by created_at desc, id desc.

func (*MongoDBStore) Update

func (s *MongoDBStore) Update(ctx context.Context, batch *StoredBatch) error

Update updates a stored batch object. It leaves the usage claim alone, and only ever sets the usage marker: one the batch carries is saved beside it too, where an update of a copy read before it cannot drop it.

type Result

type Result struct {
	Store Store
}

Result holds the initialized batch store.

func New

func New(ctx context.Context, shared storage.Storage) (*Result, error)

New creates a batch store on the shared storage connection.

func (*Result) Close

func (r *Result) Close() error

Close releases resources held by the batch store.

type SQLStore added in v0.1.60

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

SQLStore stores batches in a SQL database.

func NewSQLStore added in v0.1.60

func NewSQLStore(ctx context.Context, db sqlx.DB) (*SQLStore, error)

NewSQLStore creates the batches table and indexes if needed.

func (*SQLStore) ClaimUsage added in v0.2.4

func (s *SQLStore) ClaimUsage(ctx context.Context, id string, now time.Time, timeout time.Duration) (UsageClaim, error)

ClaimUsage grants the batch's usage claim with one conditional update, so concurrent callers cannot both take it.

func (*SQLStore) Close added in v0.1.60

func (s *SQLStore) Close() error

Close is a no-op; connection lifecycle is managed by the storage layer.

func (*SQLStore) CompleteUsage added in v0.2.4

func (s *SQLStore) CompleteUsage(ctx context.Context, id string, loggedAt time.Time) error

CompleteUsage marks the batch's usage as logged and releases the claim.

func (*SQLStore) Create added in v0.1.60

func (s *SQLStore) Create(ctx context.Context, batch *StoredBatch) error

Create inserts a new batch.

func (*SQLStore) Delete added in v0.1.60

func (s *SQLStore) Delete(ctx context.Context, id string) error

Delete removes a stored batch object.

func (*SQLStore) Get added in v0.1.60

func (s *SQLStore) Get(ctx context.Context, id string) (*StoredBatch, error)

Get returns a batch by id.

func (*SQLStore) List added in v0.1.60

func (s *SQLStore) List(ctx context.Context, limit int, after, userPath string) ([]*StoredBatch, error)

List returns batches ordered by created_at desc, id desc, optionally confined to one user-path subtree.

func (*SQLStore) Update added in v0.1.60

func (s *SQLStore) Update(ctx context.Context, batch *StoredBatch) error

Update updates a stored batch object. It leaves the usage claim alone, and only ever sets the usage marker: one the batch carries is saved beside it too, where an update of a copy read before it cannot drop it.

type Store

type Store interface {
	Create(ctx context.Context, batch *StoredBatch) error
	Get(ctx context.Context, id string) (*StoredBatch, error)
	// List returns batches newest first, starting after the cursor id. A
	// non-empty userPath keeps only batches inside that subtree (the path
	// itself and its descendants); the cursor must lie inside it too, else
	// ErrNotFound.
	List(ctx context.Context, limit int, after, userPath string) ([]*StoredBatch, error)
	// Update replaces the stored batch. It never clears a stored
	// UsageLoggedAt and never touches a usage claim, so saving a copy read
	// before the batch's usage was logged does not make it count again. A
	// UsageLoggedAt the batch carries is stored.
	Update(ctx context.Context, batch *StoredBatch) error
	// ClaimUsage asks for the right to write the batch's usage entries at
	// now. The claim is granted when nobody holds one, or when the one held
	// is at least timeout old and so belongs to a writer that stopped. Of
	// concurrent callers exactly one is granted the claim.
	ClaimUsage(ctx context.Context, id string, now time.Time, timeout time.Duration) (UsageClaim, error)
	// CompleteUsage records that every usage entry of the batch was handed
	// to the usage logger at loggedAt, and releases the claim.
	CompleteUsage(ctx context.Context, id string, loggedAt time.Time) error
	Delete(ctx context.Context, id string) error
	Close() error
}

Store defines persistence operations for batch lifecycle APIs.

type StoredBatch

type StoredBatch struct {
	Batch                     *core.BatchResponse `json:"batch"`
	RequestEndpointByCustomID map[string]string   `json:"request_endpoint_by_custom_id,omitempty"`
	OriginalInputFileID       string              `json:"original_input_file_id,omitempty"`
	RewrittenInputFileID      string              `json:"rewritten_input_file_id,omitempty"`
	RequestID                 string              `json:"request_id,omitempty"`
	// ProviderName is the configured provider instance the batch was sent to.
	// Batch.Provider only carries its type, which is not enough to apply the
	// instance's settings (billable, pricing overrides) to its usage rows.
	ProviderName      string     `json:"provider_name,omitempty"`
	UserPath          string     `json:"user_path,omitempty"`
	SessionID         string     `json:"session_id,omitempty"`
	AuthKeyID         string     `json:"auth_key_id,omitempty"`
	WorkflowVersionID string     `json:"workflow_version_id,omitempty"`
	UsageEnabled      *bool      `json:"usage_enabled,omitempty"`
	UsageLoggedAt     *time.Time `json:"usage_logged_at,omitempty"`
}

StoredBatch keeps the public batch response separate from gateway-only persistence hints that should never be exposed by API DTOs.

func (*StoredBatch) EffectiveUsageEnabled

func (s *StoredBatch) EffectiveUsageEnabled() bool

EffectiveUsageEnabled reports whether batch usage logging should run. Nil means the value was not persisted by older versions, so usage remains enabled.

type UsageClaim added in v0.2.4

type UsageClaim int

UsageClaim is the outcome of Store.ClaimUsage.

const (
	// UsagePending means another writer holds a claim younger than the
	// timeout: it is writing the entries now, or stopped a moment ago.
	UsagePending UsageClaim = iota
	// UsageClaimed means the caller holds the claim and writes the entries.
	UsageClaimed
	// UsageLogged means the entries were already written.
	UsageLogged
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL