README
¶
RiverKit
Compose library jobs into one host-owned River client. RiverKit registers every contribution before construction, validates the combined worker/queue/schedule set, then binds request-side producers before returning the unstarted client. It does not migrate storage, own the PostgreSQL pool, or start/stop workers.
jobs, err := riverkit.New(ctx, pool, &river.Config{Schema: "public"},
auth.RiverJobs(), billing.RiverJobs())
if err != nil { return err }
if err := jobs.Start(ctx); err != nil { return err }
defer jobs.Stop(context.Background())
Libraries return opaque Contribution values from RiverJobs(). Their
registration function adds to the supplied config; their private bind callback
receives the final client. An abort callback invalidates partially composed
library state after failure. It must never close the host pool or an existing
successful host fleet. Contributions are single-use; libraries must also guard
against creating a second descriptor for the same runtime.
Queue settings supplied by the host are preserved. Contributions may add queues and share existing queues with identical settings, but cannot replace the worker registry, change the queue schema, overwrite prior queue settings, or remove existing schedules. Duplicate workers/schedule IDs return errors before binding. River's checked periodic API is used immediately after client construction and before any binding or start; all contributions have already registered by then.
A failed composition consumes the descriptors it claimed. Close those library runtimes and construct new ones. All replicas using the same River tables must compose the same complete periodic schedule set, because only the elected leader schedules periodic jobs. Migration ownership remains the host/library decision.
Run go test -race ./... and go vet ./....
Bind callbacks receive a Binding with the final Client and its actual Pool. Libraries can qualify transactional database identity before enabling producers. The host owns both lifetimes; callbacks must never close the pool.
RiverKit defaults an omitted queue schema to explicit public. Set river.Config.Schema for another namespace. Jobs never depend on a worker or caller transaction connection's search_path.
Documentation
¶
Overview ¶
Package riverkit composes library workers into one host-owned River client. It does not migrate a database, own a pool, or start or stop the returned client.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func New ¶
func New(ctx context.Context, pool *pgxpool.Pool, options *river.Config, jobs ...Contribution) (client *river.Client[pgx.Tx], err error)
New registers every contribution before constructing one unstarted client, then binds its producers. A failed composition consumes its contributions; discard the participating library runtimes and construct fresh ones. The input config's maps and slices are copied. An existing Workers registry may be extended during registration and must also be discarded on failure.
Types ¶
type Binding ¶ added in v0.2.0
Binding is the final client and the exact pool used to construct it. Both are borrowed from the host: contributions must not start/stop the client or close the pool. A contribution may use Pool to verify its transactional producers address the same physical database before enabling them.
type Contribution ¶
type Contribution struct {
// contains filtered or unexported fields
}
Contribution is one library's startup registration and producer binding. Copies share the same single-use identity. Libraries also guard their own lifecycle so requesting a fresh contribution cannot compose a runtime twice.
func Group ¶
func Group(jobs ...Contribution) Contribution
Group bundles a library's own jobs with already attached components. It does not register or bind anything. Children are flattened before any composition validation, so duplicate registrations cannot hide inside a group.
func NewContribution ¶
func NewContribution(name string, register func(context.Context, *river.Config) error, bind func(context.Context, Binding) error, abort func() error) Contribution
NewContribution describes one library's jobs. register adds workers, active queues and periodic jobs; bind attaches the final unstarted client to any request-side producers. abort must invalidate partial registration/binding and release only the library's composition resources, never the host pool. Construction is side-effect free. Nil bind/abort hooks are allowed for a stateless contribution with no producer or resources to clean up. A bind callback requires an abort callback to invalidate any partial producer binding.
Source Files