httpapi

package
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Jul 22, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

Documentation

Overview

Package httpapi exposes BlockQueue as a versioned, cross-language HTTP API. It provides strict JSON decoding, RFC 9457 errors, bounded cursor pagination, health endpoints, OpenAPI 3.1, and optional authentication middleware. Transactional queue methods intentionally remain Go-only because a remote request cannot join the caller's database transaction.

Index

Constants

View Source
const MaximumPollDuration = 60 * time.Second

MaximumPollDuration is the longest claim request accepted by the HTTP API.

View Source
const MinimumWriteTimeout = MaximumPollDuration + 5*time.Second

MinimumWriteTimeout leaves five seconds to encode and write a response after the longest supported claim poll completes.

Variables

This section is empty.

Functions

func PrincipalFromContext added in v0.3.0

func PrincipalFromContext(ctx context.Context) (string, bool)

PrincipalFromContext returns the subject installed by PrincipalResolver.

func Router

func Router(queue *blockqueue.Queue, options Options) http.Handler

Router builds the health, OpenAPI, dashboard, and versioned API routes.

Types

type BatchNackRequest

type BatchNackRequest struct {
	MessageID    string `json:"message_id"`
	ReceiptToken string `json:"receipt_token"`
	RetryDelay   string `json:"retry_delay,omitempty"`
	Error        string `json:"error,omitempty"`
}

type BatchReceiptRequest

type BatchReceiptRequest struct {
	MessageID    string `json:"message_id"`
	ReceiptToken string `json:"receipt_token"`
}

type CancelRequest

type CancelRequest struct {
	Reason string `json:"reason,omitempty"`
}

type ErrorMapper

type ErrorMapper func(error) (status int, code, message string)

ErrorMapper converts domain failures into stable HTTP problem fields.

type Handler

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

Handler implements the versioned queue HTTP contract over Service.

func New

func New(service Service, mapper ErrorMapper) *Handler

New constructs an HTTP handler with an optional domain error mapper.

func (*Handler) Attach

func (h *Handler) Attach(root chi.Router)

Attach registers all version-relative routes on root.

type LeaseRequest

type LeaseRequest struct {
	ReceiptToken string `json:"receipt_token"`
	Extension    string `json:"extension,omitempty"`
}

type NackRequest

type NackRequest struct {
	ReceiptToken string `json:"receipt_token"`
	RetryDelay   string `json:"retry_delay,omitempty"`
	Error        string `json:"error,omitempty"`
}

type Options

type Options struct {
	// Prefix defaults to /v1. Handler.Attach can be used directly when the
	// embedding application wants to own all routing decisions.
	Prefix    string
	UIPath    string
	DisableUI bool
	// AuthMiddleware is applied only to the versioned API. Health checks,
	// OpenAPI, and static UI remain available for the embedding application to
	// protect at a wider router boundary when desired.
	AuthMiddleware func(http.Handler) http.Handler
	// PrincipalResolver is optional. When set, resolution failure or an empty
	// subject returns an RFC 9457 401 response before AuthMiddleware runs.
	PrincipalResolver PrincipalResolver
}

Options configures API routing, dashboard serving, and authentication hooks.

type PrincipalResolver added in v0.3.0

type PrincipalResolver func(*http.Request) (string, error)

PrincipalResolver authenticates a request and returns the stable subject exposed to downstream authorization middleware and handlers. A nil resolver keeps the HTTP package authentication-neutral.

type PublishRequest

type PublishRequest struct {
	Message        string            `json:"message"`
	Headers        map[string]string `json:"headers,omitempty"`
	CorrelationID  string            `json:"correlation_id,omitempty"`
	IdempotencyKey string            `json:"idempotency_key,omitempty"`
	Priority       int               `json:"priority,omitempty"`
	Delay          string            `json:"delay,omitempty"`
	ScheduleAt     string            `json:"schedule_at,omitempty"`
}

type ReceiptRequest

type ReceiptRequest struct {
	ReceiptToken string `json:"receipt_token"`
}

type ReplayRequest

type ReplayRequest struct {
	MessageIDs []string `json:"message_ids"`
}

type ScheduleRequest

type ScheduleRequest struct {
	Name           string            `json:"name"`
	CronExpression string            `json:"cron"`
	Timezone       string            `json:"timezone,omitempty"`
	Message        string            `json:"message"`
	Headers        map[string]string `json:"headers,omitempty"`
	CorrelationID  string            `json:"correlation_id,omitempty"`
	Priority       int               `json:"priority,omitempty"`
	MisfirePolicy  string            `json:"misfire_policy,omitempty"`
	OverlapPolicy  string            `json:"overlap_policy,omitempty"`
}

type ScheduleUpdateRequest

type ScheduleUpdateRequest struct {
	Version int `json:"version"`
	ScheduleRequest
}

type Service

type Service interface {
	ListTopics(context.Context, int, string) (blockqueue.TopicPage, error)
	GetTopic(string) (blockqueue.Topic, bool)
	CreateTopic(context.Context, blockqueue.Topic, blockqueue.Subscribers) error
	DeleteTopic(context.Context, blockqueue.Topic) error
	ListSubscriberStatuses(context.Context, blockqueue.Topic, int, string) (blockqueue.SubscriberStatusPage, error)
	CreateSubscribers(context.Context, blockqueue.Topic, blockqueue.Subscribers) error
	DeleteSubscriber(context.Context, blockqueue.Topic, string) error
	PublishAsync(context.Context, blockqueue.Topic, blockqueue.Message) (blockqueue.PublishReceipt, error)
	PublishDurable(context.Context, blockqueue.Topic, blockqueue.Message) (blockqueue.PublishReceipt, error)
	BatchPublishAsync(context.Context, blockqueue.Topic, []blockqueue.Message) (blockqueue.PublishReceipts, error)
	BatchPublishDurable(context.Context, blockqueue.Topic, []blockqueue.Message) (blockqueue.PublishReceipts, error)
	GetMessageStatus(context.Context, blockqueue.Topic, string) (blockqueue.MessageStatus, error)
	ClaimWait(context.Context, blockqueue.Topic, string, int, time.Duration) (blockqueue.Deliveries, error)
	AckDelivery(context.Context, blockqueue.Topic, string, string, string) error
	NackDelivery(context.Context, blockqueue.Topic, string, string, string, time.Duration, string) error
	ExtendLease(context.Context, blockqueue.Topic, string, string, string, time.Duration) (time.Time, error)
	BatchAckDeliveries(context.Context, blockqueue.Topic, string, []blockqueue.BatchAckItem) []blockqueue.DeliveryResult
	BatchNackDeliveries(context.Context, blockqueue.Topic, string, []blockqueue.BatchNackItem) []blockqueue.DeliveryResult
	SnoozeDelivery(context.Context, blockqueue.Topic, string, string, string, time.Duration) (time.Time, error)
	CancelDelivery(context.Context, blockqueue.Topic, string, string, string) error
	CancelMessage(context.Context, blockqueue.Topic, string, string) ([]blockqueue.DeliveryResult, error)
	DeliveryErrors(context.Context, blockqueue.Topic, string, string, int, string) (blockqueue.DeliveryErrorPage, error)
	ListDeliveries(context.Context, blockqueue.Topic, string, bool, int, string) (blockqueue.DeliveryPage, error)
	ReplayDeadLetters(context.Context, blockqueue.Topic, string, []string) []blockqueue.DeliveryResult
	PauseTopic(context.Context, blockqueue.Topic) error
	ResumeTopic(context.Context, blockqueue.Topic) error
	PauseSubscriber(context.Context, blockqueue.Topic, string) error
	ResumeSubscriber(context.Context, blockqueue.Topic, string) error
	ListSchedulesPage(context.Context, blockqueue.Topic, int, string) (blockqueue.SchedulePage, error)
	CreateSchedule(context.Context, blockqueue.Topic, blockqueue.ScheduleInput) (blockqueue.Schedule, error)
	GetSchedule(context.Context, blockqueue.Topic, string) (blockqueue.Schedule, error)
	UpdateSchedule(context.Context, blockqueue.Topic, string, int, blockqueue.ScheduleInput) (blockqueue.Schedule, error)
	DeleteSchedule(context.Context, blockqueue.Topic, string) error
	PauseSchedule(context.Context, blockqueue.Topic, string, bool) error
	RunScheduleNow(context.Context, blockqueue.Topic, string, bool) (blockqueue.ScheduleRun, error)
	ScheduleRunHistory(context.Context, blockqueue.Topic, string, int, string) (blockqueue.ScheduleRunPage, error)
}

Service is the application port consumed by the HTTP transport.

type SnoozeRequest

type SnoozeRequest struct {
	ReceiptToken string `json:"receipt_token"`
	Delay        string `json:"delay"`
}

type SubscriberOptions

type SubscriberOptions struct {
	MaxAttempts        int                    `json:"max_attempts"`
	VisibilityDuration string                 `json:"visibility_duration"`
	DequeueBatchSize   int                    `json:"dequeue_batch_size,omitempty"`
	RetryPolicy        blockqueue.RetryPolicy `json:"retry_policy,omitempty"`
}

type SubscriberRequest

type SubscriberRequest struct {
	Name   string            `json:"name"`
	Option SubscriberOptions `json:"option"`
}

type TopicRequest

type TopicRequest struct {
	Name        string              `json:"name"`
	Subscribers []SubscriberRequest `json:"subscribers"`
}

Jump to

Keyboard shortcuts

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