Documentation
¶
Overview ¶
Package queueservice preserves the released queue service import path.
Deprecated: use github.com/faustbrian/go-queue/adapters/service.
Index ¶
- Constants
- Variables
- type CallbackError
- type CallbackOperation
- type CallbackPanicError
- type Check
- type CloseAdmission
- type Handler
- type HandlerOptions
- type LifecycleWorker
- type LifecycleWorkerOptions
- type OptionsError
- type Producer
- func (producer *Producer[R]) Component() service.Component
- func (producer *Producer[R]) Publish(ctx context.Context, message core.QueuedMessage, options ...job.AllowOption) (correlation.Values, error)
- func (producer *Producer[R]) PublishWithAcceptance(ctx context.Context, message core.QueuedMessage, options ...job.AllowOption) (correlation.Values, PublishAcceptance, error)
- func (producer *Producer[R]) Readiness() (service.ReadinessCheck, bool)
- func (producer *Producer[R]) Resource() R
- type ProducerOptions
- type Publish
- type PublishAcceptance
- type PublishError
- type PublishWithAcceptance
- type Run
- type Shutdown
- type Startup
- type StartupError
- type Worker
- type WorkerOptions
Examples ¶
Constants ¶
const MaxNameBytes = successor.MaxNameBytes
MaxNameBytes bounds component, task, and readiness identifiers.
Variables ¶
var ( // ErrInvalidOptions identifies invalid adapter construction. ErrInvalidOptions = successor.ErrInvalidOptions ErrUnavailable = successor.ErrUnavailable // ErrMissingCorrelation reports a publish without an explicit parent workflow. ErrMissingCorrelation = successor.ErrMissingCorrelation // ErrCallbackPanic reports a recovered application callback panic. ErrCallbackPanic = successor.ErrCallbackPanic // ErrPublishOutcomeUnknown reports a publish that may have reached the backend. ErrPublishOutcomeUnknown = successor.ErrPublishOutcomeUnknown // ErrInvalidPublishAcceptance reports a result outside the acceptance contract. ErrInvalidPublishAcceptance = successor.ErrInvalidPublishAcceptance // ErrWorkerExited reports a worker that returned before cancellation. ErrWorkerExited = successor.ErrWorkerExited )
Functions ¶
This section is empty.
Types ¶
type CallbackError ¶
type CallbackError struct {
// Operation identifies the callback boundary.
Operation CallbackOperation
// Err is the original callback failure.
Err error
}
CallbackError preserves a callback cause without formatting its text.
func (*CallbackError) Error ¶
func (err *CallbackError) Error() string
Error returns a secret-safe callback failure.
func (*CallbackError) Unwrap ¶
func (err *CallbackError) Unwrap() error
Unwrap preserves the callback cause for errors.Is and errors.As.
type CallbackOperation ¶
type CallbackOperation uint8
CallbackOperation identifies an application callback boundary.
const ( // CallbackStartup identifies resource validation during service start. CallbackStartup CallbackOperation = 1 // CallbackReadiness identifies an opt-in dependency readiness check. CallbackReadiness CallbackOperation = 2 // CallbackPublish identifies concrete producer publication. CallbackPublish CallbackOperation = 3 // CallbackHandler identifies application task handling. CallbackHandler CallbackOperation = 4 // CallbackRun identifies supervised worker intake. CallbackRun CallbackOperation = 5 // CallbackShutdown identifies transferred resource cleanup. CallbackShutdown CallbackOperation = 6 // CallbackAdmission identifies synchronous worker intake closure. CallbackAdmission CallbackOperation = 7 )
type CallbackPanicError ¶
type CallbackPanicError struct {
// Operation identifies the callback boundary without retaining its panic value.
Operation CallbackOperation
}
CallbackPanicError identifies a recovered callback without retaining its value.
func (*CallbackPanicError) Error ¶
func (err *CallbackPanicError) Error() string
Error returns a secret-safe callback failure.
func (*CallbackPanicError) Unwrap ¶
func (*CallbackPanicError) Unwrap() error
Unwrap exposes the stable panic classification.
type CloseAdmission ¶
CloseAdmission synchronously and idempotently stops new worker intake.
type Handler ¶
type Handler func(context.Context, core.TaskMessage) error
Handler processes one queue delivery within the supplied context.
func NewHandler ¶
func NewHandler(options HandlerOptions) (Handler, error)
NewHandler validates and wraps one correlation-aware delivery handler.
type HandlerOptions ¶
type HandlerOptions struct {
// Correlation creates per-delivery request identifiers.
Correlation *correlation.Factory
// CorrelationOptions configure queue metadata propagation.
CorrelationOptions queuecorrelation.Options
// TrustedMetadata permits authenticated incoming correlation metadata.
TrustedMetadata bool
// TracePropagator extracts caller-approved telemetry context when non-nil.
TracePropagator propagation.TextMapPropagator
// Handler processes the decoded task.
Handler Handler
}
HandlerOptions configure correlation and tracing around one task handler.
type LifecycleWorker ¶
type LifecycleWorker[R any] struct { // contains filtered or unexported fields }
LifecycleWorker coordinates startup, intake, drain, and shutdown for a resource.
func NewLifecycleWorker ¶
func NewLifecycleWorker[R any](options LifecycleWorkerOptions[R]) (*LifecycleWorker[R], error)
NewLifecycleWorker validates and constructs a supervised typed worker.
Example ¶
package main
import (
"context"
"errors"
"fmt"
"time"
"github.com/faustbrian/go-correlation"
"github.com/faustbrian/go-queue/core"
"github.com/faustbrian/go-queue/queueservice"
)
type typedWorkerResource struct{}
type typedDelivery string
func (delivery typedDelivery) Bytes() []byte { return []byte(delivery) }
func (delivery typedDelivery) Payload() []byte { return []byte(delivery) }
func main() {
factory, _ := correlation.NewFactory(correlation.FactoryOptions{})
worker, err := queueservice.NewLifecycleWorker(
queueservice.LifecycleWorkerOptions[*typedWorkerResource]{
Name: "orders-worker",
Resource: &typedWorkerResource{},
Correlation: factory,
Handler: func(_ context.Context, task core.TaskMessage) error {
fmt.Println(string(task.Payload()))
return nil
},
Run: func(
ctx context.Context,
_ *typedWorkerResource,
handler queueservice.Handler,
) error {
return handler(ctx, typedDelivery("delivery"))
},
Shutdown: func(context.Context, *typedWorkerResource) error {
return nil
},
},
)
if err != nil {
return
}
plan := worker.Plan()
if err = plan.Components[0].Start(context.Background()); err != nil {
return
}
if err = plan.Tasks[0].Run(context.Background()); !errors.Is(err, queueservice.ErrWorkerExited) {
return
}
stopContext, cancel := context.WithTimeout(context.Background(), time.Second)
defer cancel()
if err = plan.Components[0].Stop(stopContext); err != nil {
return
}
}
Output: delivery
func (*LifecycleWorker[R]) Plan ¶
func (worker *LifecycleWorker[R]) Plan() service.Plan
Plan returns the component, task, and optional readiness check under one identity.
func (*LifecycleWorker[R]) Resource ¶
func (worker *LifecycleWorker[R]) Resource() R
Resource returns the exact caller-provided worker resource.
type LifecycleWorkerOptions ¶
type LifecycleWorkerOptions[R any] struct { // Name is the stable service identity. Name string // Resource is the caller-constructed worker resource. Resource R // Correlation creates per-delivery request identifiers. Correlation *correlation.Factory // CorrelationOptions configure queue metadata propagation. CorrelationOptions queuecorrelation.Options // TrustedMetadata permits authenticated incoming correlation metadata. TrustedMetadata bool // TracePropagator extracts caller-approved telemetry context when non-nil. TracePropagator propagation.TextMapPropagator // Handler processes admitted deliveries. Handler Handler // Startup optionally validates Resource before intake. Startup Startup[R] // Readiness optionally checks Resource after startup. Readiness Check[R] // CloseAdmission synchronously stops new intake during drain. CloseAdmission CloseAdmission[R] // Run owns the blocking intake loop. Run Run[R] // Shutdown releases the transferred worker resource. Shutdown Shutdown[R] }
LifecycleWorkerOptions configure a typed supervised worker lifecycle.
type OptionsError ¶
type OptionsError struct {
// Field identifies the rejected option.
Field string
// Reason describes the safe failure category.
Reason string
}
OptionsError identifies one rejected option without exposing sensitive values.
func (*OptionsError) Error ¶
func (err *OptionsError) Error() string
Error returns a secret-safe construction diagnostic.
func (*OptionsError) Unwrap ¶
func (*OptionsError) Unwrap() error
Unwrap exposes the stable option classification.
type Producer ¶
type Producer[R any] struct { // contains filtered or unexported fields }
Producer retains a concrete producer and coordinates its in-flight calls.
func NewProducer ¶
func NewProducer[R any](options ProducerOptions[R]) (*Producer[R], error)
NewProducer validates and constructs a lifecycle-aware producer.
func (*Producer[R]) Component ¶
Component returns the service lifecycle component for this producer.
func (*Producer[R]) Publish ¶
func (producer *Producer[R]) Publish(ctx context.Context, message core.QueuedMessage, options ...job.AllowOption) (correlation.Values, error)
Publish appends one correlation-aware task and returns its propagated values.
func (*Producer[R]) PublishWithAcceptance ¶
func (producer *Producer[R]) PublishWithAcceptance(ctx context.Context, message core.QueuedMessage, options ...job.AllowOption) (correlation.Values, PublishAcceptance, error)
PublishWithAcceptance appends one task and reports its backend acceptance.
type ProducerOptions ¶
type ProducerOptions[R any] struct { // Name is the secret-safe component name. Name string // Resource is the caller-constructed concrete producer. Resource R // Correlation creates message-hop identifiers. Correlation *correlation.Factory // CorrelationOptions configure queue propagation. CorrelationOptions queuecorrelation.Options // TracePropagator injects caller-owned telemetry context when non-nil. TracePropagator propagation.TextMapPropagator // Startup optionally validates Resource before admission begins. Startup Startup[R] // Readiness optionally checks Resource after successful startup. Readiness Check[R] // Publish performs one concrete caller-bounded append. Publish Publish[R] // PublishWithAcceptance performs one append with explicit acceptance. PublishWithAcceptance PublishWithAcceptance[R] // Shutdown transfers transport close ownership when non-nil. Shutdown Shutdown[R] }
ProducerOptions configure one producer lifecycle adapter.
type Publish ¶
type Publish[R any] func(context.Context, R, core.QueuedMessage, ...job.AllowOption) error
Publish appends one correlation-aware message through a concrete resource.
type PublishAcceptance ¶
type PublishAcceptance uint8
PublishAcceptance reports whether a failed publish reached the backend.
const ( // PublishNotAccepted means the backend definitively did not accept the task. PublishNotAccepted PublishAcceptance = 1 // PublishAccepted means the backend definitively accepted the task. PublishAccepted PublishAcceptance = 2 // PublishUnknown means the backend may have accepted the task. PublishUnknown PublishAcceptance = 3 )
type PublishError ¶
type PublishError struct {
// Acceptance describes whether the task reached the backend.
Acceptance PublishAcceptance
// Err is the original classifiable failure.
Err error
}
PublishError preserves the backend cause and acceptance classification.
func (*PublishError) Error ¶
func (err *PublishError) Error() string
Error returns a secret-safe publish diagnostic.
func (*PublishError) Unwrap ¶
func (err *PublishError) Unwrap() error
Unwrap preserves the backend and stable acceptance causes.
type PublishWithAcceptance ¶
type PublishWithAcceptance[R any] func(context.Context, R, core.QueuedMessage, ...job.AllowOption) (PublishAcceptance, error)
PublishWithAcceptance appends one task and classifies backend acceptance.
type StartupError ¶
type StartupError struct {
// Validation is the startup-check failure.
Validation error
// Cleanup is an optional transferred-resource shutdown failure.
Cleanup error
}
StartupError preserves validation and partial-cleanup failures.
func (*StartupError) Error ¶
func (err *StartupError) Error() string
Error returns a secret-safe startup diagnostic.
func (*StartupError) Unwrap ¶
func (err *StartupError) Unwrap() []error
Unwrap preserves both causes for errors.Is and errors.As.
type Worker ¶
type Worker struct {
// contains filtered or unexported fields
}
Worker adapts a concrete queue to the service lifecycle.
func NewWorker ¶
func NewWorker(options WorkerOptions) (*Worker, error)
NewWorker validates and constructs the concrete queue lifecycle adapter.
Example ¶
package main
import (
"context"
"fmt"
"time"
"github.com/faustbrian/go-correlation"
queue "github.com/faustbrian/go-queue"
"github.com/faustbrian/go-queue/core"
"github.com/faustbrian/go-queue/job"
"github.com/faustbrian/go-queue/queueservice"
"go.opentelemetry.io/otel/propagation"
)
type payload string
func (value payload) Bytes() []byte { return []byte(value) }
func main() {
ctx, cancel := context.WithTimeout(context.Background(), time.Second)
defer cancel()
factory, _ := correlation.NewFactory(correlation.FactoryOptions{})
handled := make(chan string, 1)
handler, err := queueservice.NewHandler(queueservice.HandlerOptions{
Correlation: factory,
TrustedMetadata: true,
TracePropagator: propagation.TraceContext{},
Handler: func(_ context.Context, task core.TaskMessage) error {
handled <- string(task.Payload())
return nil
},
})
if err != nil {
return
}
concrete, err := queue.NewQueue(
queue.WithWorker(queue.NewRing(queue.WithFn(handler))),
queue.WithWorkerCount(1),
)
if err != nil {
return
}
worker, err := queueservice.NewWorker(queueservice.WorkerOptions{
Name: "jobs-worker", Queue: concrete,
})
if err != nil {
return
}
producer, err := queueservice.NewProducer(
queueservice.ProducerOptions[*queue.Queue]{
Name: "jobs-producer", Resource: concrete, Correlation: factory,
TracePropagator: propagation.TraceContext{},
Publish: func(
_ context.Context,
resource *queue.Queue,
message core.QueuedMessage,
options ...job.AllowOption,
) error {
return resource.Queue(message, options...)
},
},
)
if err != nil {
return
}
workerComponent := worker.Component()
producerComponent := producer.Component()
if err = workerComponent.Start(ctx); err != nil {
return
}
if err = producerComponent.Start(ctx); err != nil {
return
}
parent, _ := factory.Start()
if _, err = producer.Publish(
correlation.WithValues(ctx, parent),
payload("delivery"),
); err != nil {
return
}
select {
case value := <-handled:
fmt.Println(value)
case <-ctx.Done():
return
}
if err = producerComponent.Stop(ctx); err != nil {
return
}
if err = workerComponent.Stop(ctx); err != nil {
return
}
}
Output: delivery
type WorkerOptions ¶
type WorkerOptions struct {
// Name is the stable service identity.
Name string
// Queue is the caller-constructed queue resource.
Queue *queue.Queue
}
WorkerOptions configure the concrete queue convenience adapter.