wire

package
v0.1.1 Latest Latest
Warning

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

Go to latest
Published: Jun 22, 2026 License: MIT Imports: 1 Imported by: 0

Documentation

Overview

Package wire defines the JSON-over-HTTP contract shared by the mqlite broker (server) and the Go SDK client. It mirrors the proto sketch in design §7.2. One source of truth so the two sides can never drift.

JSON conventions: `body` is base64 (Go marshals []byte as base64, matching the curl examples in §7.4); timestamps are epoch-ms integers; seq numbers are integers. Unary RPC = HTTP POST to /mqlite.v1.<Service>/<Method>.

Index

Constants

View Source
const (
	PathSend            = "/mqlite.v1.QueueService/Send"
	PathReceive         = "/mqlite.v1.QueueService/Receive"
	PathComplete        = "/mqlite.v1.QueueService/Complete"
	PathCompleteBatch   = "/mqlite.v1.QueueService/CompleteBatch"
	PathAbandon         = "/mqlite.v1.QueueService/Abandon"
	PathReject          = "/mqlite.v1.QueueService/Reject"
	PathDefer           = "/mqlite.v1.QueueService/Defer"
	PathReceiveDeferred = "/mqlite.v1.QueueService/ReceiveDeferred"
	PathRenew           = "/mqlite.v1.QueueService/Renew"
	PathSchedule        = "/mqlite.v1.QueueService/Schedule"
	PathCancel          = "/mqlite.v1.QueueService/Cancel"
	PathPeek            = "/mqlite.v1.QueueService/Peek"
	PathStats           = "/mqlite.v1.QueueService/Stats"

	PathCreateQueue = "/mqlite.v1.AdminService/CreateQueue"
	PathSubscribe   = "/mqlite.v1.AdminService/Subscribe"
	PathListQueues  = "/mqlite.v1.AdminService/ListQueues"
	PathRedrive     = "/mqlite.v1.AdminService/Redrive"
	PathPurge       = "/mqlite.v1.AdminService/Purge"
)

Route paths (Connect-style: /package.Service/Method).

Variables

This section is empty.

Functions

This section is empty.

Types

type CancelRequest

type CancelRequest struct {
	Queue     string `json:"queue"`
	SeqNumber int64  `json:"seq_number"`
}

type CompleteBatchRequest added in v0.1.1

type CompleteBatchRequest struct {
	Queue    string       `json:"queue"`
	Messages []SettleItem `json:"messages"`
}

type CompleteBatchResponse added in v0.1.1

type CompleteBatchResponse struct {
	Results []SettleItemResult `json:"results"`
}

type CreateQueueRequest

type CreateQueueRequest struct {
	Name   string          `json:"name"`
	Config QueueConfigJSON `json:"config"`
}

type Empty

type Empty struct{}

type ErrorBody

type ErrorBody struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

ErrorBody is the Connect-style JSON error envelope.

type ListQueuesResponse

type ListQueuesResponse struct {
	Queues []QueueInfoJSON `json:"queues"`
}

type Message

type Message struct {
	SeqNumber             int64             `json:"seq_number,omitempty"`
	EnqueuedAtMs          int64             `json:"enqueued_at_ms,omitempty"`
	ExpiresAtMs           int64             `json:"expires_at_ms,omitempty"`
	VisibleAtMs           int64             `json:"visible_at_ms,omitempty"`
	LockedUntilMs         int64             `json:"locked_until_ms,omitempty"`
	DeliveryCount         int               `json:"delivery_count,omitempty"`
	LockToken             string            `json:"lock_token,omitempty"`
	State                 string            `json:"state,omitempty"`
	DeadLetterReason      string            `json:"dead_letter_reason,omitempty"`
	DeadLetterDescription string            `json:"dead_letter_description,omitempty"`
	MessageID             string            `json:"message_id,omitempty"`
	CorrelationID         string            `json:"correlation_id,omitempty"`
	ReplyTo               string            `json:"reply_to,omitempty"`
	GroupID               string            `json:"group_id,omitempty"`
	ContentType           string            `json:"content_type,omitempty"`
	Subject               string            `json:"subject,omitempty"`
	Properties            map[string]string `json:"properties,omitempty"`
	Body                  []byte            `json:"body,omitempty"` // base64 in JSON
}

Message is the wire form of a message (both send input and receive output).

func FromEngineMessage

func FromEngineMessage(m *engine.Message) Message

func FromPeeked

func FromPeeked(p *engine.PeekedMessage) Message

func (Message) ToOut

func (m Message) ToOut() engine.OutMessage

type MetricsRequest

type MetricsRequest struct {
	Queue string `json:"queue"`
}

type MetricsResponse

type MetricsResponse struct {
	Queue              string `json:"queue"`
	Active             int64  `json:"active"`
	Locked             int64  `json:"locked"`
	Deferred           int64  `json:"deferred"`
	Scheduled          int64  `json:"scheduled"`
	DeadLettered       int64  `json:"dead_lettered"`
	Total              int64  `json:"total"`
	OldestMessageAgeMs int64  `json:"oldest_message_age_ms"`
}

type PeekRequest

type PeekRequest struct {
	Queue   string `json:"queue"`
	FromSeq int64  `json:"from_seq,omitempty"`
	State   string `json:"state,omitempty"`
	Max     int    `json:"max,omitempty"`
}

type PeekResponse

type PeekResponse struct {
	Messages []Message `json:"messages"`
}

type PurgeRequest

type PurgeRequest struct {
	Queue       string `json:"queue"`
	Max         int    `json:"max,omitempty"`
	OlderThanMs int64  `json:"older_than_ms,omitempty"`
}

type PurgeResponse

type PurgeResponse struct {
	Purged int `json:"purged"`
}

type QueueConfigJSON

type QueueConfigJSON struct {
	Kind               string `json:"kind,omitempty"`
	LockDurationMs     int64  `json:"lock_duration_ms,omitempty"`
	MaxDeliveryCount   int    `json:"max_delivery_count,omitempty"`
	DefaultTTLMs       int64  `json:"default_ttl_ms,omitempty"`
	DeadLetterOnExpire *bool  `json:"dead_letter_on_expire,omitempty"`
	DedupWindowMs      int64  `json:"dedup_window_ms,omitempty"`
	OrderingMode       string `json:"ordering_mode,omitempty"`
	// Per-queue DLQ retention overrides (MQLITE-29): 0 inherits the broker default,
	// >0 sets this queue's bound, -1 is explicitly unbounded.
	DLQMaxAgeMs int64 `json:"dlq_max_age_ms,omitempty"`
	DLQMaxCount int   `json:"dlq_max_count,omitempty"`
	DLQMaxBytes int64 `json:"dlq_max_bytes,omitempty"`
}

func (QueueConfigJSON) ToConfig

func (c QueueConfigJSON) ToConfig() engine.QueueConfig

type QueueInfoJSON

type QueueInfoJSON struct {
	Name             string `json:"name"`
	Kind             string `json:"kind"`
	LockDurationMs   int64  `json:"lock_duration_ms"`
	MaxDeliveryCount int    `json:"max_delivery_count"`
	DefaultTTLMs     int64  `json:"default_ttl_ms"`
	DedupWindowMs    int64  `json:"dedup_window_ms"`
}

type ReceiveDeferredRequest

type ReceiveDeferredRequest struct {
	Queue      string  `json:"queue"`
	SeqNumbers []int64 `json:"seq_numbers"`
}

type ReceiveRequest

type ReceiveRequest struct {
	Queue       string `json:"queue"`
	MaxMessages int    `json:"max_messages,omitempty"`
	WaitTimeMs  int64  `json:"wait_time_ms,omitempty"`
	ReceiveMode int    `json:"receive_mode,omitempty"`       // 0=peek-lock, 1=receive-and-delete
	AttemptID   string `json:"receive_attempt_id,omitempty"` // idempotency key for retried receives
}

type ReceiveResponse

type ReceiveResponse struct {
	Messages []Message `json:"messages"`
}

type RedriveRequest

type RedriveRequest struct {
	Queue       string `json:"queue"`
	Target      string `json:"target,omitempty"`
	Max         int    `json:"max,omitempty"`
	OlderThanMs int64  `json:"older_than_ms,omitempty"`
	RatePerSec  int    `json:"rate_per_sec,omitempty"`
}

type RedriveResponse

type RedriveResponse struct {
	Moved int `json:"moved"`
}

type SendRequest

type SendRequest struct {
	Queue                  string    `json:"queue"`
	Messages               []Message `json:"messages"`
	ScheduledEnqueueTimeMs int64     `json:"scheduled_enqueue_time_ms,omitempty"`
	TTLMs                  int64     `json:"ttl_ms,omitempty"`
}

type SendResponse

type SendResponse struct {
	SeqNumbers []int64 `json:"seq_numbers"`
}

SendResponse returns one sequence number per input message, positionally. In a multi-message batch a slot is 0 when that message hit a dedup conflict (same message_id, different body): the offending message is skipped so the rest of the batch still commits, and seq 0 marks the slot that was NOT enqueued. A single-message Send instead surfaces that conflict as a 409 (already_exists) rather than a 200 with a 0, so a non-batch client never has to special-case it.

type SettleItem added in v0.1.1

type SettleItem struct {
	SeqNumber int64  `json:"seq_number"`
	LockToken string `json:"lock_token"`
}

CompleteBatch settles many messages in one round-trip (fixes the drain N+1).

type SettleItemResult added in v0.1.1

type SettleItemResult struct {
	SeqNumber int64 `json:"seq_number"`
	Ok        bool  `json:"ok"`
}

type SettleRequest

type SettleRequest struct {
	Queue                 string `json:"queue"`
	SeqNumber             int64  `json:"seq_number"`
	LockToken             string `json:"lock_token"`
	DeadLetterReason      string `json:"dead_letter_reason,omitempty"`
	DeadLetterDescription string `json:"dead_letter_description,omitempty"`
	DelayMs               int64  `json:"delay_ms,omitempty"` // Abandon backoff
}

type SettleResponse

type SettleResponse struct {
	Ok bool `json:"ok"`
}

type SubscribeRequest

type SubscribeRequest struct {
	Topic  string         `json:"topic"`
	Name   string         `json:"name"`
	Filter *engine.Filter `json:"filter,omitempty"`
}

Jump to

Keyboard shortcuts

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