feat: expose result subscription HTTP and WebSocket APIs

2026-09-17 19:57:55 +08:00
parent 1c3300cc5b
commit 8485a662b2
38 changed files with 3462 additions and 26 deletions
--- a/internal/transport/httpserver/event_codec.go
+++ b/internal/transport/httpserver/event_codec.go
@@ -0,0 +1,175 @@
+package httpserver
+
+import (
+	"bytes"
+	"encoding/json"
+	"io"
+	"mime"
+	"net/http"
+	"reflect"
+	"strconv"
+	"strings"
+	"time"
+
+	"git.yuntuo.hk/k2safe/orbit/internal/fault"
+	"git.yuntuo.hk/k2safe/orbit/internal/jsonvalue"
+	core "git.yuntuo.hk/k2safe/orbit/model"
+)
+
+const EventSubprotocol = "orbit.events.v1"
+const eventMaxFrame = 512 << 10
+
+type eventFrame struct {
+	Version   string          `json:"protocol_version"`
+	Type      string          `json:"type"`
+	MessageID core.ID         `json:"message_id"`
+	ReplyTo   core.ID         `json:"reply_to,omitempty"`
+	SessionID core.ID         `json:"session_id,omitempty"`
+	Body      json.RawMessage `json:"body,omitempty"`
+	Error     *fault.Error    `json:"error,omitempty"`
+}
+type eventHello struct {
+	SubscriptionID core.ID `json:"subscription_id"`
+	Capacity       uint32  `json:"capacity"`
+}
+type eventWelcome struct {
+	SessionID           core.ID   `json:"session_id"`
+	SubscriptionID      core.ID   `json:"subscription_id"`
+	Capacity            uint32    `json:"capacity"`
+	LeaseDurationMS     int64     `json:"lease_duration_ms"`
+	HeartbeatIntervalMS int64     `json:"heartbeat_interval_ms"`
+	ServerTime          time.Time `json:"server_time"`
+	Enabled             bool      `json:"enabled"`
+}
+type eventPong struct {
+	ServerTime time.Time `json:"server_time"`
+	Enabled    bool      `json:"enabled"`
+}
+
+func decodeEventBody(r *http.Request, out any) error {
+	content, _, err := mime.ParseMediaType(r.Header.Get("Content-Type"))
+	if err != nil || content != "application/json" {
+		return fault.New("UNSUPPORTED_MEDIA_TYPE", "Content-Type must be application/json")
+	}
+	raw, err := io.ReadAll(io.LimitReader(r.Body, eventMaxFrame+1))
+	if err != nil {
+		return fault.Invalid("cannot read request body")
+	}
+	if len(raw) > eventMaxFrame {
+		return fault.New("BODY_TOO_LARGE", "request body exceeds 512 KiB")
+	}
+	return decodeEventJSON(raw, out)
+}
+func decodeEventJSON(raw []byte, out any) error {
+	if len(raw) == 0 || len(raw) > eventMaxFrame {
+		return fault.Invalid("invalid event message size")
+	}
+	if _, err := jsonvalue.Canonical(raw); err != nil {
+		return fault.Invalid("invalid event JSON")
+	}
+	typ := reflect.TypeOf(out).Elem()
+	if exactFields(raw, typ) != nil || requiredEventFields(raw, typ) != nil {
+		return fault.Invalid("missing, unknown or invalid event field")
+	}
+	d := json.NewDecoder(bytes.NewReader(raw))
+	d.DisallowUnknownFields()
+	if d.Decode(out) != nil {
+		return fault.Invalid("invalid event field value")
+	}
+	return nil
+}
+
+// requiredEventFields 同时验证显式控制意图及规范十进制字符串；可选历史游标允许0和null。
+func requiredEventFields(raw []byte, typ reflect.Type) error {
+	if typ == reflect.TypeOf(json.RawMessage{}) || typ == reflect.TypeOf(time.Time{}) {
+		return nil
+	}
+	if typ.Kind() == reflect.Pointer {
+		if bytes.Equal(bytes.TrimSpace(raw), []byte("null")) {
+			return nil
+		}
+		return requiredEventFields(raw, typ.Elem())
+	}
+	if typ.Kind() == reflect.Array || typ.Kind() == reflect.Slice {
+		var values []json.RawMessage
+		if json.Unmarshal(raw, &values) != nil {
+			return fault.Invalid("invalid event array")
+		}
+		for _, v := range values {
+			if err := requiredEventFields(v, typ.Elem()); err != nil {
+				return err
+			}
+		}
+		return nil
+	}
+	if typ.Kind() != reflect.Struct {
+		return nil
+	}
+	var fields map[string]json.RawMessage
+	if json.Unmarshal(raw, &fields) != nil {
+		return fault.Invalid("invalid event object")
+	}
+	for i := 0; i < typ.NumField(); i++ {
+		field := typ.Field(i)
+		tags := strings.Split(field.Tag.Get("json"), ",")
+		if tags[0] == "" || tags[0] == "-" {
+			continue
+		}
+		optional, numberString := false, false
+		for _, v := range tags[1:] {
+			optional = optional || v == "omitempty"
+			numberString = numberString || v == "string"
+		}
+		value, found := fields[tags[0]]
+		if !found {
+			if optional {
+				continue
+			}
+			return fault.Invalid("missing event field")
+		}
+		ft := field.Type
+		nullable := ft.Kind() == reflect.Pointer
+		if nullable {
+			if bytes.Equal(bytes.TrimSpace(value), []byte("null")) {
+				continue
+			}
+			ft = ft.Elem()
+		}
+		if ft.Kind() == reflect.Uint64 && numberString {
+			var text string
+			if json.Unmarshal(value, &text) != nil {
+				return fault.Invalid("event counter must be a decimal string")
+			}
+			n, err := strconv.ParseUint(text, 10, 64)
+			if err != nil || strconv.FormatUint(n, 10) != text || (!nullable && n == 0) {
+				return fault.Invalid("invalid event counter")
+			}
+		}
+		if err := requiredEventFields(value, field.Type); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+func decodeEventRequest(raw []byte, hello bool) (eventFrame, error) {
+	var frame eventFrame
+	if err := decodeEventJSON(raw, &frame); err != nil {
+		return frame, err
+	}
+	if frame.Version != "1" || frame.MessageID.Validate() != nil || len(frame.Body) == 0 {
+		return frame, fault.Invalid("invalid event envelope")
+	}
+	var fields map[string]json.RawMessage
+	_ = json.Unmarshal(raw, &fields)
+	if fields["error"] != nil || fields["reply_to"] != nil {
+		return frame, fault.Invalid("response fields are not allowed in event requests")
+	}
+	if hello {
+		if frame.Type != "events.hello" || fields["session_id"] != nil {
+			return frame, fault.Invalid("invalid event hello")
+		}
+	} else if frame.SessionID.Validate() != nil || (frame.Type != "event.ack" && frame.Type != "events.ping") {
+		return frame, fault.Invalid("invalid event session or type")
+	}
+	return frame, nil
+}
--- a/internal/transport/httpserver/event_codec_test.go
+++ b/internal/transport/httpserver/event_codec_test.go
@@ -0,0 +1,141 @@
+package httpserver
+
+import (
+	"encoding/json"
+	"os"
+	"strings"
+	"testing"
+
+	"git.yuntuo.hk/k2safe/orbit/internal/testcontract"
+	"git.yuntuo.hk/k2safe/orbit/platform/events"
+)
+
+func TestEventFrameContract(t *testing.T) {
+	id := strings.Repeat("1", 32)
+	secret, _, err := events.NewSecret()
+	if err != nil {
+		t.Fatal(err)
+	}
+	valid := []string{
+		`{"protocol_version":"1","type":"events.hello","message_id":"` + id + `","body":{"subscription_id":"` + id + `","capacity":1}}`,
+		`{"protocol_version":"1","type":"events.ping","message_id":"` + id + `","session_id":"` + id + `","body":{}}`,
+		`{"protocol_version":"1","type":"event.ack","message_id":"` + id + `","session_id":"` + id + `","body":{"delivery_id":"` + id + `","epoch":"1","lease_secret":"` + secret + `"}}`,
+	}
+	for i, raw := range valid {
+		testcontract.EventFrame(t, "client", []byte(raw))
+		f, err := decodeEventRequest([]byte(raw), i == 0)
+		if err != nil {
+			t.Fatal(err)
+		}
+		switch i {
+		case 0:
+			var v eventHello
+			err = decodeEventJSON(f.Body, &v)
+		case 1:
+			var v struct{}
+			err = decodeEventJSON(f.Body, &v)
+		case 2:
+			var v events.AckInput
+			err = decodeEventJSON(f.Body, &v)
+		}
+		if err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	for _, number := range []string{"0", "01", "18446744073709551616", "18446744073709551615"} {
+		raw := strings.Replace(valid[2], `"epoch":"1"`, `"epoch":"`+number+`"`, 1)
+		var frame eventFrame
+		_ = json.Unmarshal([]byte(raw), &frame)
+		var input events.AckInput
+		decodeErr := decodeEventJSON(frame.Body, &input)
+		var value any
+		_ = json.Unmarshal([]byte(raw), &value)
+		schemaErr := testcontract.EventSchema(t, "client").Validate(value)
+		wantValid := number == "18446744073709551615"
+		if (decodeErr == nil) != wantValid || (schemaErr == nil) != wantValid {
+			t.Fatal("event counter range disagrees with contract")
+		}
+	}
+	bad := []string{
+		strings.Replace(valid[0], `"body":`, `"session_id":null,"body":`, 1),
+		strings.Replace(valid[1], `"body":`, `"reply_to":"","body":`, 1),
+		strings.Replace(valid[1], `"body":`, `"error":null,"body":`, 1),
+		strings.Replace(valid[1], `"type":"events.ping"`, `"Type":"events.ping"`, 1),
+		strings.Replace(valid[1], `"protocol_version":"1"`, `"protocol_version":"1","protocol_version":"1"`, 1),
+		strings.Replace(valid[1], `"events.ping"`, `"worker.capacity"`, 1),
+		strings.Replace(valid[1], `"body":{}`, `"body":null`, 1),
+	}
+	for _, raw := range bad {
+		if _, err := decodeEventRequest([]byte(raw), strings.Contains(raw, "events.hello")); err == nil {
+			t.Fatal("accepted invalid event envelope")
+		}
+	}
+	// 标准Schema无法识别重复JSON键；实际解码器负责拒绝，其他方向约束由两者共同验证。
+	for _, raw := range bad[:4] {
+		var value any
+		if err := json.Unmarshal([]byte(raw), &value); err != nil {
+			t.Fatal(err)
+		}
+		if testcontract.EventSchema(t, "client").Validate(value) == nil {
+			t.Fatal("schema accepted direction or field violation")
+		}
+	}
+}
+func TestEventHTTPRequiredFieldsAndCounterCanonicalization(t *testing.T) {
+	id := strings.Repeat("1", 32)
+	for _, number := range []string{`"00"`, `"+1"`, `"01"`, `1`, `true`, `"18446744073709551616"`} {
+		var in events.CreateInput
+		raw := `{"name":"results","queue_id":"` + id + `","from_sequence":` + number + `}`
+		if decodeEventJSON([]byte(raw), &in) == nil {
+			t.Fatal("accepted invalid sequence")
+		}
+	}
+	for _, number := range []string{`"0"`, `null`, `"18446744073709551615"`} {
+		var in events.CreateInput
+		if err := decodeEventJSON([]byte(`{"name":"results","queue_id":"`+id+`","from_sequence":`+number+`}`), &in); err != nil {
+			t.Fatal(err)
+		}
+	}
+	for _, raw := range []string{`{"expected_revision":"1","reason":"pause"}`, `{"expected_revision":"01","reason":"pause","enabled":false}`, `{"expected_revision":"1","reason":"pause","enabled":null}`, `{"expected_revision":"1","reason":"pause","Enabled":false}`} {
+		var in events.ControlInput
+		if decodeEventJSON([]byte(raw), &in) == nil {
+			t.Fatal("accepted ambiguous control intent")
+		}
+	}
+	var good events.ControlInput
+	if err := decodeEventJSON([]byte(`{"expected_revision":"1","reason":"pause","enabled":false}`), &good); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestEventDocumentationFramesMatchPublishedSchema(t *testing.T) {
+	raw, err := os.ReadFile("../../../docs/api/subscriptions.md")
+	if err != nil {
+		t.Fatal(err)
+	}
+	frames := 0
+	for _, block := range strings.Split(string(raw), "```json\n")[1:] {
+		snippet := strings.SplitN(block, "\n```", 2)[0]
+		var value map[string]json.RawMessage
+		if json.Unmarshal([]byte(snippet), &value) != nil {
+			t.Fatal("invalid documented JSON")
+		}
+		if value["protocol_version"] == nil {
+			continue
+		}
+		var kind string
+		if json.Unmarshal(value["type"], &kind) != nil {
+			t.Fatal("documented frame lacks type")
+		}
+		side := "server"
+		if kind == "events.hello" || kind == "events.ping" || kind == "event.ack" {
+			side = "client"
+		}
+		testcontract.EventFrame(t, side, []byte(snippet))
+		frames++
+	}
+	if frames != 6 {
+		t.Fatalf("expected six complete documented frames, got %d", frames)
+	}
+}
--- a/internal/transport/httpserver/event_hub.go
+++ b/internal/transport/httpserver/event_hub.go
@@ -0,0 +1,356 @@
+package httpserver
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"strings"
+	"sync"
+	"time"
+
+	"git.yuntuo.hk/k2safe/orbit/internal/dispatch"
+	"git.yuntuo.hk/k2safe/orbit/internal/fault"
+	"git.yuntuo.hk/k2safe/orbit/internal/jsonwire"
+	core "git.yuntuo.hk/k2safe/orbit/model"
+	"git.yuntuo.hk/k2safe/orbit/platform/auth"
+	"git.yuntuo.hk/k2safe/orbit/platform/events"
+	"github.com/coder/websocket"
+)
+
+// EventHub 仅负责已持久化结果的传输；断线不删除租约，消费者按事件ID持久化去重。
+// 节点最多128条连接，领取池全局4个、每应用1个在途，队列加在途共128个。
+type EventHub struct {
+	service  *events.Service
+	ctx      context.Context
+	cancel   context.CancelFunc
+	mu       sync.Mutex
+	closing  bool
+	slots    chan struct{}
+	wg       sync.WaitGroup
+	dispatch *dispatch.Pool
+	poll     time.Duration
+}
+
+func NewEventHub(parent context.Context, service *events.Service) *EventHub {
+	ctx, cancel := context.WithCancel(parent)
+	h := &EventHub{service: service, ctx: ctx, cancel: cancel, slots: make(chan struct{}, 128), poll: time.Second}
+	h.dispatch = dispatch.New(ctx, 4, 128)
+	h.wg.Add(1)
+	go func() { defer h.wg.Done(); <-h.dispatch.Done() }()
+	return h
+}
+func RegisterEventConsumers(server *http.Server, hub *EventHub) {
+	server.Handler.(*http.ServeMux).Handle("GET /v1/events/connect", hub)
+}
+func (h *EventHub) Shutdown(ctx context.Context) error {
+	h.mu.Lock()
+	h.closing = true
+	h.cancel()
+	h.mu.Unlock()
+	done := make(chan struct{})
+	go func() { h.wg.Wait(); close(done) }()
+	select {
+	case <-done:
+		return nil
+	case <-ctx.Done():
+		return ctx.Err()
+	}
+}
+func (h *EventHub) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	requestID, err := core.NewID()
+	if err != nil {
+		writeError(w, "", fault.Unavailable)
+		return
+	}
+	w.Header().Set("X-Request-ID", string(requestID))
+	w.Header().Set("Cache-Control", "no-store")
+	w.Header().Set("X-Content-Type-Options", "nosniff")
+	if err = noEventQuery(r); err != nil {
+		writeError(w, string(requestID), err)
+		return
+	}
+	values := r.Header.Values("Authorization")
+	if len(values) != 1 {
+		writeError(w, string(requestID), fault.Unauthorized)
+		return
+	}
+	scheme, value, ok := strings.Cut(values[0], " ")
+	if !ok || !strings.EqualFold(scheme, "Bearer") {
+		writeError(w, string(requestID), fault.Unauthorized)
+		return
+	}
+	token, err := auth.Parse(value)
+	if err != nil {
+		writeError(w, string(requestID), err)
+		return
+	}
+	supported := false
+	for _, header := range r.Header.Values("Sec-WebSocket-Protocol") {
+		for _, p := range strings.Split(header, ",") {
+			supported = supported || strings.TrimSpace(p) == EventSubprotocol
+		}
+	}
+	if !supported {
+		writeJSON(w, http.StatusUpgradeRequired, map[string]any{"request_id": requestID, "error": fault.New("PROTOCOL_REQUIRED", "orbit.events.v1 subprotocol is required")})
+		return
+	}
+	h.mu.Lock()
+	if h.closing || h.ctx.Err() != nil {
+		h.mu.Unlock()
+		writeError(w, string(requestID), fault.Unavailable)
+		return
+	}
+	select {
+	case h.slots <- struct{}{}:
+		h.wg.Add(1)
+	default:
+		h.mu.Unlock()
+		w.Header().Set("Retry-After", "1")
+		writeJSON(w, 429, map[string]any{"request_id": requestID, "error": fault.New("CAPACITY_EXCEEDED", "node event connection capacity exceeded")})
+		return
+	}
+	h.mu.Unlock()
+	defer func() { <-h.slots; h.wg.Done() }()
+	authorize, stop := context.WithTimeout(r.Context(), 5*time.Second)
+	err = h.service.Authorize(authorize, token)
+	stop()
+	if err != nil {
+		writeError(w, string(requestID), err)
+		return
+	}
+	conn, err := websocket.Accept(w, r, &websocket.AcceptOptions{Subprotocols: []string{EventSubprotocol}, CompressionMode: websocket.CompressionDisabled})
+	if err != nil {
+		return
+	}
+	defer conn.CloseNow()
+	conn.SetReadLimit(eventMaxFrame)
+	ctx, cancel := context.WithCancel(h.ctx)
+	defer cancel()
+	helloCtx, helloStop := context.WithTimeout(ctx, 5*time.Second)
+	kind, raw, err := conn.Read(helloCtx)
+	helloStop()
+	if err != nil {
+		return
+	}
+	frame, decodeErr := decodeEventRequest(raw, true)
+	var input eventHello
+	if kind != websocket.MessageText || decodeErr != nil || decodeEventJSON(frame.Body, &input) != nil || input.SubscriptionID.Validate() != nil || input.Capacity < 1 || input.Capacity > 32 {
+		_ = conn.Close(websocket.StatusPolicyViolation, "invalid event hello")
+		return
+	}
+	call, callStop := context.WithTimeout(ctx, 8*time.Second)
+	binding, err := h.service.Bind(call, token, input.SubscriptionID)
+	callStop()
+	if err != nil {
+		_ = writeEventFrame(ctx, conn, eventFrame{Version: "1", Type: "error", MessageID: requestID, ReplyTo: frame.MessageID, Error: eventFault(err)})
+		return
+	}
+	session, err := core.NewID()
+	if err != nil {
+		return
+	}
+	welcome := eventWelcome{SessionID: session, SubscriptionID: input.SubscriptionID, Capacity: input.Capacity, LeaseDurationMS: events.LeaseDuration.Milliseconds(), HeartbeatIntervalMS: 15000, ServerTime: binding.ServerTime, Enabled: binding.Enabled}
+	body, err := jsonwire.Marshal(welcome)
+	if err != nil {
+		return
+	}
+	if err = writeEventFrame(ctx, conn, eventFrame{Version: "1", Type: "events.welcome", MessageID: requestID, ReplyTo: frame.MessageID, SessionID: session, Body: body}); err != nil {
+		return
+	}
+	h.consume(ctx, cancel, conn, token, binding, session, input.Capacity)
+}
+
+type eventClaimResult struct {
+	grant *events.Grant
+	err   error
+}
+
+func (h *EventHub) claim(ctx context.Context, t auth.Token, sub, connection core.ID, capacity uint32) (out eventClaimResult) {
+	defer func() {
+		if recover() != nil {
+			out = eventClaimResult{err: fault.Unavailable}
+		}
+	}()
+	call, stop := context.WithTimeout(ctx, 8*time.Second)
+	defer stop()
+	out.grant, out.err = h.service.Claim(call, t, sub, events.ClaimInput{ConnectionID: connection, Capacity: capacity})
+	return out
+}
+func (h *EventHub) consume(ctx context.Context, cancel context.CancelFunc, conn *websocket.Conn, t auth.Token, b events.ConsumerBinding, session core.ID, capacity uint32) {
+	incoming := make(chan eventFrame, 4)
+	outgoing := make(chan outboundFrame, 8)
+	var loops sync.WaitGroup
+	loops.Add(2)
+	go func() {
+		defer loops.Done()
+		defer cancel()
+		for {
+			readCtx, stop := context.WithTimeout(ctx, 60*time.Second)
+			kind, raw, err := conn.Read(readCtx)
+			stop()
+			if err != nil {
+				return
+			}
+			frame, err := decodeEventRequest(raw, false)
+			if kind != websocket.MessageText || err != nil || frame.SessionID != session {
+				_ = conn.Close(websocket.StatusPolicyViolation, "invalid event frame")
+				return
+			}
+			select {
+			case incoming <- frame:
+			case <-ctx.Done():
+				return
+			}
+		}
+	}()
+	go func() {
+		defer loops.Done()
+		defer cancel()
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case frame := <-outgoing:
+				writeCtx, stop := context.WithTimeout(ctx, 5*time.Second)
+				err := conn.Write(writeCtx, websocket.MessageText, frame.data)
+				stop()
+				if frame.done != nil {
+					frame.done <- err
+				}
+				if err != nil {
+					return
+				}
+			}
+		}
+	}()
+	defer func() { cancel(); _ = conn.CloseNow(); loops.Wait() }()
+	send := func(frame eventFrame, wait bool) bool {
+		frame.Version = "1"
+		frame.SessionID = session
+		if frame.MessageID == "" {
+			var err error
+			frame.MessageID, err = core.NewID()
+			if err != nil {
+				return false
+			}
+		}
+		raw, err := jsonwire.Marshal(frame)
+		if err != nil || len(raw) > eventMaxFrame {
+			return false
+		}
+		out := outboundFrame{data: raw}
+		if wait {
+			out.done = make(chan error, 1)
+		}
+		select {
+		case outgoing <- out:
+		default:
+			return false
+		}
+		if !wait {
+			return true
+		}
+		select {
+		case err := <-out.done:
+			return err == nil
+		case <-ctx.Done():
+			return false
+		}
+	}
+	results := make(chan eventClaimResult, 1)
+	pending, burst := false, 0
+	request := func() {
+		if pending || burst == 0 || len(outgoing) >= 4 {
+			return
+		}
+		pending = h.dispatch.Submit(dispatch.Job{Context: ctx, Application: string(b.ApplicationID), Queue: string(t.NamespaceID) + "/" + string(b.SubscriptionID), Run: func(job context.Context) { results <- h.claim(job, t, b.SubscriptionID, session, capacity) }})
+		if pending {
+			burst--
+		}
+	}
+	ticker := time.NewTicker(h.poll)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case result := <-results:
+			pending = false
+			if result.err != nil {
+				send(eventFrame{Type: "error", Error: eventFault(result.err)}, true)
+				return
+			}
+			if result.grant == nil {
+				burst = 0
+				continue
+			}
+			raw, err := jsonwire.Marshal(result.grant)
+			if err != nil || !send(eventFrame{Type: "event.deliver", Body: raw}, false) {
+				return
+			}
+			request()
+		case frame := <-incoming:
+			call, stop := context.WithTimeout(ctx, 8*time.Second)
+			var body any
+			var err error
+			switch frame.Type {
+			case "event.ack":
+				var in events.AckInput
+				if err = decodeEventJSON(frame.Body, &in); err == nil {
+					body, err = h.service.Ack(call, t, b.SubscriptionID, in)
+				}
+			case "events.ping":
+				var in struct{}
+				if err = decodeEventJSON(frame.Body, &in); err == nil {
+					var current events.ConsumerBinding
+					current, err = h.service.Bind(call, t, b.SubscriptionID)
+					if err == nil {
+						body = eventPong{ServerTime: current.ServerTime, Enabled: current.Enabled}
+					}
+				}
+			default:
+				err = fault.Invalid("unsupported event message type")
+			}
+			stop()
+			reply := eventFrame{Type: "ack", ReplyTo: frame.MessageID}
+			if err != nil {
+				reply.Type = "error"
+				reply.Error = eventFault(err)
+			} else {
+				var marshalErr error
+				reply.Body, marshalErr = jsonwire.Marshal(body)
+				if marshalErr != nil {
+					return
+				}
+			}
+			fatal := err != nil && (fault.Code(err) == "UNAUTHENTICATED" || fault.Code(err) == "PERMISSION_DENIED" || fault.Code(err) == "NOT_FOUND" || fault.Code(err) == "UNAVAILABLE")
+			if !send(reply, fatal) || fatal {
+				return
+			}
+		case <-ticker.C:
+			if !pending {
+				burst = 4
+				request()
+			}
+		}
+	}
+}
+func eventFault(err error) *fault.Error {
+	var known *fault.Error
+	if errors.As(err, &known) {
+		return known
+	}
+	return fault.Unavailable
+}
+func writeEventFrame(ctx context.Context, conn *websocket.Conn, frame eventFrame) error {
+	raw, err := jsonwire.Marshal(frame)
+	if err != nil {
+		return err
+	}
+	if len(raw) > eventMaxFrame {
+		return fault.Invalid("event frame too large")
+	}
+	bounded, stop := context.WithTimeout(ctx, 5*time.Second)
+	defer stop()
+	return conn.Write(bounded, websocket.MessageText, raw)
+}
--- a/internal/transport/httpserver/event_hub_test.go
+++ b/internal/transport/httpserver/event_hub_test.go
@@ -0,0 +1,139 @@
+package httpserver
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"git.yuntuo.hk/k2safe/orbit/internal/jsonwire"
+	core "git.yuntuo.hk/k2safe/orbit/model"
+	"git.yuntuo.hk/k2safe/orbit/platform/auth"
+	"git.yuntuo.hk/k2safe/orbit/platform/events"
+	"github.com/coder/websocket"
+)
+
+type slowEventStore struct {
+	events.Store
+	once     sync.Once
+	started  chan struct{}
+	finished chan struct{}
+}
+
+func (s *slowEventStore) AuthorizeEvents(context.Context, auth.Token) error { return nil }
+func (s *slowEventStore) BindConsumer(_ context.Context, _ auth.Token, id core.ID) (events.ConsumerBinding, error) {
+	return events.ConsumerBinding{ApplicationID: core.ID(strings.Repeat("1", 32)), SubscriptionID: id, QueueID: core.ID(strings.Repeat("2", 32)), Enabled: true, ServerTime: time.Now().UTC()}, nil
+}
+func (s *slowEventStore) ClaimDelivery(ctx context.Context, _ auth.Token, _ core.ID, _ events.ClaimInput) (*events.Grant, error) {
+	s.once.Do(func() { close(s.started) })
+	<-ctx.Done()
+	select {
+	case s.finished <- struct{}{}:
+	default:
+	}
+	return nil, ctx.Err()
+}
+func TestEventHubSlowClaimKeepsControlLiveAndBoundsConnections(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+	store := &slowEventStore{started: make(chan struct{}), finished: make(chan struct{}, 4)}
+	hub := NewEventHub(ctx, events.New(store))
+	if cap(hub.slots) != 128 {
+		t.Fatal("unexpected production connection bound")
+	}
+	hub.slots = make(chan struct{}, 2)
+	hub.poll = 10 * time.Millisecond
+	server := New("", nil)
+	RegisterEventConsumers(server, hub)
+	tls := httptest.NewTLSServer(server.Handler)
+	defer tls.Close()
+	defer hub.Shutdown(context.Background())
+	id := core.ID(strings.Repeat("3", 32))
+	credential := core.ID(strings.Repeat("4", 32))
+	token, _, err := auth.Issue(id, credential)
+	if err != nil {
+		t.Fatal(err)
+	}
+	headers := http.Header{}
+	headers.Set("Authorization", "Bearer "+token)
+	dial := func() (*websocket.Conn, *http.Response, error) {
+		return websocket.Dial(ctx, strings.Replace(tls.URL, "https://", "wss://", 1)+"/v1/events/connect", &websocket.DialOptions{HTTPClient: tls.Client(), HTTPHeader: headers, Subprotocols: []string{EventSubprotocol}})
+	}
+	connect := func() (*websocket.Conn, core.ID) {
+		t.Helper()
+		conn, _, err := dial()
+		if err != nil {
+			t.Fatal(err)
+		}
+		t.Cleanup(func() { conn.CloseNow() })
+		hello, _ := jsonwire.Marshal(eventHello{SubscriptionID: id, Capacity: 1})
+		raw, _ := jsonwire.Marshal(eventFrame{Version: "1", Type: "events.hello", MessageID: id, Body: hello})
+		if err = conn.Write(ctx, websocket.MessageText, raw); err != nil {
+			t.Fatal(err)
+		}
+		_, reply, err := conn.Read(ctx)
+		if err != nil {
+			t.Fatal(err)
+		}
+		var frame eventFrame
+		if json.Unmarshal(reply, &frame) != nil || frame.Type != "events.welcome" {
+			t.Fatal("missing welcome")
+		}
+		return conn, frame.SessionID
+	}
+	first, session := connect()
+	second, _ := connect()
+	select {
+	case <-store.started:
+	case <-ctx.Done():
+		t.Fatal("claim was not dispatched")
+	}
+	blocked, resp, err := dial()
+	if blocked != nil {
+		blocked.CloseNow()
+	}
+	if err == nil || resp == nil || resp.StatusCode != 429 || resp.Header.Get("Retry-After") != "1" {
+		t.Fatal("event connection bound not enforced")
+	}
+	ping, _ := jsonwire.Marshal(eventFrame{Version: "1", Type: "events.ping", MessageID: credential, SessionID: session, Body: json.RawMessage(`{}`)})
+	if err = first.Write(ctx, websocket.MessageText, ping); err != nil {
+		t.Fatal(err)
+	}
+	bounded, stop := context.WithTimeout(ctx, 500*time.Millisecond)
+	_, raw, err := first.Read(bounded)
+	stop()
+	if err != nil {
+		t.Fatal("slow claim blocked control reply")
+	}
+	var reply eventFrame
+	if json.Unmarshal(raw, &reply) != nil || reply.Type != "ack" || reply.ReplyTo != credential {
+		t.Fatal("missing ping acknowledgement")
+	}
+	second.CloseNow()
+	deadline := time.Now().Add(time.Second)
+	for len(hub.slots) == 2 && time.Now().Before(deadline) {
+		time.Sleep(time.Millisecond)
+	}
+	if len(hub.slots) != 1 {
+		t.Fatal("disconnected consumer leaked connection slot")
+	}
+	third, _ := connect()
+	defer third.CloseNow()
+	bounded, stop = context.WithTimeout(ctx, time.Second)
+	defer stop()
+	if err = hub.Shutdown(bounded); err != nil {
+		t.Fatal("shutdown leaked claim or connection", err)
+	}
+	select {
+	case <-store.finished:
+	default:
+		t.Fatal("shutdown did not cancel in-flight claim")
+	}
+	if len(hub.slots) != 0 {
+		t.Fatal("shutdown leaked connection slots")
+	}
+}
--- a/internal/transport/httpserver/events.go
+++ b/internal/transport/httpserver/events.go
@@ -0,0 +1,128 @@
+package httpserver
+
+import (
+	"net/http"
+	"net/url"
+	"strconv"
+	"strings"
+
+	"git.yuntuo.hk/k2safe/orbit/internal/fault"
+	core "git.yuntuo.hk/k2safe/orbit/model"
+	"git.yuntuo.hk/k2safe/orbit/platform/auth"
+	"git.yuntuo.hk/k2safe/orbit/platform/events"
+	platform "git.yuntuo.hk/k2safe/orbit/platform/model"
+)
+
+func RegisterEventSubscriptions(server *http.Server, s *events.Service) {
+	mux := server.Handler.(*http.ServeMux)
+	mux.HandleFunc("POST /v1/subscriptions", wrap(func(r *http.Request, t auth.Token) (any, int, error) {
+		if err := noEventQuery(r); err != nil {
+			return nil, 0, err
+		}
+		var in events.CreateInput
+		if err := decodeEventBody(r, &in); err != nil {
+			return nil, 0, err
+		}
+		key, err := idempotencyKey(r)
+		if err != nil {
+			return nil, 0, err
+		}
+		out, err := s.Create(r.Context(), t, key, in)
+		return out, createdStatus(out.Deduplicated), err
+	}))
+	mux.HandleFunc("GET /v1/subscriptions", wrap(func(r *http.Request, t auth.Token) (any, int, error) {
+		queue, in, err := eventQuery(r, true)
+		if err != nil {
+			return nil, 0, err
+		}
+		out, err := s.List(r.Context(), t, queue, in)
+		return out, 200, err
+	}))
+	mux.HandleFunc("GET /v1/subscriptions/{id}", wrap(func(r *http.Request, t auth.Token) (any, int, error) {
+		if err := noEventQuery(r); err != nil {
+			return nil, 0, err
+		}
+		out, err := s.Get(r.Context(), t, core.ID(r.PathValue("id")))
+		return out, 200, err
+	}))
+	mux.HandleFunc("POST /v1/subscriptions/{command}", wrap(func(r *http.Request, t auth.Token) (any, int, error) {
+		id, command, ok := strings.Cut(r.PathValue("command"), ":")
+		if !ok || command != "configure" {
+			return nil, 0, fault.NotFound
+		}
+		if err := noEventQuery(r); err != nil {
+			return nil, 0, err
+		}
+		var in events.ControlInput
+		if err := decodeEventBody(r, &in); err != nil {
+			return nil, 0, err
+		}
+		key, err := idempotencyKey(r)
+		if err != nil {
+			return nil, 0, err
+		}
+		out, err := s.Control(r.Context(), t, core.ID(id), key, in)
+		return out, 200, err
+	}))
+	mux.HandleFunc("GET /v1/subscriptions/{id}/deliveries", wrap(func(r *http.Request, t auth.Token) (any, int, error) {
+		_, in, err := eventQuery(r, false)
+		if err != nil {
+			return nil, 0, err
+		}
+		out, err := s.Deliveries(r.Context(), t, core.ID(r.PathValue("id")), in)
+		return out, 200, err
+	}))
+	mux.HandleFunc("GET /v1/subscriptions/{id}/deliveries/{delivery}", wrap(func(r *http.Request, t auth.Token) (any, int, error) {
+		if err := noEventQuery(r); err != nil {
+			return nil, 0, err
+		}
+		out, err := s.Detail(r.Context(), t, core.ID(r.PathValue("id")), core.ID(r.PathValue("delivery")))
+		return out, 200, err
+	}))
+	mux.HandleFunc("POST /v1/subscriptions/{id}/deliveries/{command}", wrap(func(r *http.Request, t auth.Token) (any, int, error) {
+		delivery, command, ok := strings.Cut(r.PathValue("command"), ":")
+		if !ok || command != "retry" {
+			return nil, 0, fault.NotFound
+		}
+		if err := noEventQuery(r); err != nil {
+			return nil, 0, err
+		}
+		var in events.RetryInput
+		if err := decodeEventBody(r, &in); err != nil {
+			return nil, 0, err
+		}
+		key, err := idempotencyKey(r)
+		if err != nil {
+			return nil, 0, err
+		}
+		out, err := s.Retry(r.Context(), t, core.ID(r.PathValue("id")), core.ID(delivery), key, in)
+		return out, 200, err
+	}))
+}
+func noEventQuery(r *http.Request) error {
+	if r.URL.RawQuery != "" || r.URL.ForceQuery {
+		return fault.Invalid("query parameters are not allowed")
+	}
+	return nil
+}
+func eventQuery(r *http.Request, subscriptions bool) (core.ID, events.PageInput, error) {
+	var in events.PageInput
+	q, err := url.ParseQuery(r.URL.RawQuery)
+	if err != nil {
+		return "", in, fault.Invalid("invalid query encoding")
+	}
+	for k, v := range q {
+		if len(v) != 1 || (k != "limit" && k != "cursor" && !(subscriptions && k == "queue_id") && !(!subscriptions && k == "state")) {
+			return "", in, fault.Invalid("invalid subscription query")
+		}
+	}
+	if q.Has("limit") {
+		in.Limit, err = strconv.Atoi(q.Get("limit"))
+		if err != nil || in.Limit < 1 || strconv.Itoa(in.Limit) != q.Get("limit") {
+			return "", in, fault.Invalid("invalid limit")
+		}
+	}
+	in.Cursor = q.Get("cursor")
+	in.State = platform.DeliveryState(q.Get("state"))
+	return core.ID(q.Get("queue_id")), in, nil
+}
--- a/internal/transport/httpserver/tasks.go
+++ b/internal/transport/httpserver/tasks.go
@@ -185,7 +185,7 @@ func writeError(w http.ResponseWriter, id string, err error) {
 	if !errors.As(err, &known) {
 		known = fault.Unavailable
 	}
-	status := map[string]int{"INVALID_ARGUMENT": 400, "UNAUTHENTICATED": 401, "PERMISSION_DENIED": 403, "NOT_FOUND": 404, "STATE_CONFLICT": 409, "IDEMPOTENCY_CONFLICT": 409, "BODY_TOO_LARGE": 413, "UNSUPPORTED_MEDIA_TYPE": 415}[known.Code]
+	status := map[string]int{"INVALID_ARGUMENT": 400, "UNAUTHENTICATED": 401, "PERMISSION_DENIED": 403, "NOT_FOUND": 404, "STATE_CONFLICT": 409, "IDEMPOTENCY_CONFLICT": 409, "BODY_TOO_LARGE": 413, "UNSUPPORTED_MEDIA_TYPE": 415, "DELIVERY_LEASE_LOST": 409, "EVENT_HISTORY_EXPIRED": 410, "SUBSCRIPTION_LIMIT": 409}[known.Code]
 	if status == 0 {
 		status = 503
 	}