queueservice

package module
v1.1.0 Latest Latest
Warning

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

Go to latest
Published: Oct 22, 2026 License: MIT Imports: 13 Imported by: 0

README

Queue service lifecycle compatibility facade

Deprecated: use github.com/faustbrian/go-queue/adapters/service. This released v1 path delegates to that semantic owner without copying mutable runtime state.

queueservice is the independently versioned lifecycle integration between github.com/faustbrian/go-queue and github.com/faustbrian/go-service. It connects caller-owned producers and workers to service startup, readiness, supervision, drain, and shutdown without choosing a backend or moving retry, scheduling, acknowledgement, redelivery, or dead-letter policy out of queue.

The module is a deprecated stable-v1 compatibility facade at queueservice/v1.0.3. It requires Go 1.27.0 or later, and consumers should pin an exact released version.

Install

go get github.com/faustbrian/go-queue/queueservice@v1

Quick start

producer, err := queueservice.NewProducer(
	queueservice.ProducerOptions[*queue.Queue]{
		Name:        "orders-producer",
		Resource:    concreteQueue,
		Correlation: correlationFactory,
		Publish: func(
			_ context.Context,
			resource *queue.Queue,
			message core.QueuedMessage,
			options ...job.AllowOption,
		) error {
			return resource.Queue(message, options...)
		},
	},
)
if err != nil {
	return err
}

runtime, err := service.New(service.Config{
	Components: []service.Component{producer.Component()},
})
if err != nil {
	return err
}

The facade-owned executable examples contain complete imports and setup and are checked by this module's documentation gate.

Guarantees and limitations

The successor guide defines ownership, failure semantics, bounds, concurrency, security, and unsupported behavior. Do not infer additional guarantees beyond the documented module boundary.

Documentation

For ecosystem-wide selection and ownership guidance, see the versioned Golib ecosystem index and Persistence and durability family guidance.

Compatibility and support

This module follows Semantic Versioning.

License

MIT. See LICENSE.

Documentation

Overview

Package queueservice preserves the released queue service import path.

Deprecated: use github.com/faustbrian/go-queue/adapters/service.

Index

Examples

Constants

View Source
const MaxNameBytes = successor.MaxNameBytes

MaxNameBytes bounds component, task, and readiness identifiers.

Variables

View Source
var (
	// ErrInvalidOptions identifies invalid adapter construction.
	ErrInvalidOptions = successor.ErrInvalidOptions
	// ErrUnavailable reports an inactive or draining adapter.
	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 Check

type Check[R any] func(context.Context, R) error

Check evaluates whether a resource can accept new work.

type CloseAdmission

type CloseAdmission[R any] func(R) error

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

func (producer *Producer[R]) Component() service.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.

func (*Producer[R]) Readiness

func (producer *Producer[R]) Readiness() (service.ReadinessCheck, bool)

Readiness returns the optional dependency readiness check.

func (*Producer[R]) Resource

func (producer *Producer[R]) Resource() R

Resource returns the exact caller-provided producer resource.

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 Run

type Run[R any] func(context.Context, R, Handler) error

Run owns one blocking worker intake loop until cancellation or failure.

type Shutdown

type Shutdown[R any] func(context.Context, R) error

Shutdown releases an explicitly transferred producer resource.

type Startup

type Startup[R any] func(context.Context, R) error

Startup validates an explicitly constructed resource before admission.

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

func (*Worker) Component

func (worker *Worker) Component() service.Component

Component starts, drains, and releases the queue through service lifecycle hooks.

func (*Worker) Queue

func (worker *Worker) Queue() *queue.Queue

Queue returns the exact caller-provided queue.

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.

Jump to

Keyboard shortcuts

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