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
- func PrincipalFromContext(ctx context.Context) (string, bool)
- func Router(queue *blockqueue.Queue, options Options) http.Handler
- type BatchNackRequest
- type BatchReceiptRequest
- type CancelRequest
- type ErrorMapper
- type Handler
- type LeaseRequest
- type NackRequest
- type Options
- type PrincipalResolver
- type PublishRequest
- type ReceiptRequest
- type ReplayRequest
- type ScheduleRequest
- type ScheduleUpdateRequest
- type Service
- type SnoozeRequest
- type SubscriberOptions
- type SubscriberRequest
- type TopicRequest
Constants ¶
const MaximumPollDuration = 60 * time.Second
MaximumPollDuration is the longest claim request accepted by the HTTP API.
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
PrincipalFromContext returns the subject installed by PrincipalResolver.
Types ¶
type BatchNackRequest ¶
type BatchReceiptRequest ¶
type CancelRequest ¶
type CancelRequest struct {
Reason string `json:"reason,omitempty"`
}
type ErrorMapper ¶
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.
type LeaseRequest ¶
type NackRequest ¶
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
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 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"`
}