@lovrozagar/honey 0.6.8 → 0.7.1

package/src/client/ws.ts

@@ -1,54 +1,81 @@
 export type TypedWebSocket = {
 	close(code?: number, reason?: string): void
-	off(event: "close" | "error" | "message" | "open", handler: (...args: never[]) => void): void
+	off(event: "binary" | "close" | "error" | "message" | "open", handler: (...args: never[]) => void): void
+	/** Binary frames, as `ArrayBuffer`. Text frames go to `"message"`. */
+	on(event: "binary", handler: (data: ArrayBuffer) => void): void
 	on(event: "close", handler: (code: number, reason: string) => void): void
 	on(event: "error", handler: (error: unknown) => void): void
+	/** Text frames. */
 	on(event: "message", handler: (data: string) => void): void
 	on(event: "open", handler: () => void): void
 	readonly readyState: number
-	send(data: ArrayBuffer | ArrayBufferView | object | string): void
+	/**
+	 * Strings, `ArrayBuffer`, typed arrays and `Blob` are sent as-is; any other value is
+	 * JSON-encoded. Sends before the socket opens are queued; after it closes they are dropped.
+	 */
+	send(data: ArrayBuffer | ArrayBufferView | Blob | object | string): void
 }
 
 export type WSOptions = {
 	protocols?: string | string[]
 }
 
+type Payload = Blob | string | Uint8Array<ArrayBuffer>
+
+const EVENTS = new Set(["binary", "close", "error", "message", "open"])
+
 export function createTypedWebSocket(
 	url: string,
 	opts?: WSOptions,
 	WebSocketImpl: typeof WebSocket = WebSocket,
 ): TypedWebSocket {
 	const ws = opts?.protocols ? new WebSocketImpl(url, opts.protocols) : new WebSocketImpl(url)
+	ws.binaryType = "arraybuffer"
 
-	/* map user handlers → wrapped listeners for proper removal */
-	const listenerMap = new WeakMap<(...args: never[]) => void, EventListener>()
-	/* buffer sends until OPEN */
-	const sendBuffer: Array<string | Uint8Array<ArrayBuffer>> = []
-	let buffering = true
+	/* user handler → wrapped listener, per event, so one handler can be registered for several events */
+	const listeners = new Map<string, WeakMap<(...args: never[]) => void, EventListener>>()
+	/* queue sends until OPEN; stop queueing for good once the socket closes or fails */
+	const sendBuffer: Payload[] = []
+	let state: "closed" | "connecting" | "open" = "connecting"
 
 	ws.addEventListener("open", () => {
-		buffering = false
+		state = "open"
 		for (const msg of sendBuffer) {
 			ws.send(msg)
 		}
 		sendBuffer.length = 0
 	})
+	ws.addEventListener("close", () => {
+		state = "closed"
+		sendBuffer.length = 0
+	})
 
 	function close(code?: number, reason?: string) {
-		buffering = false
+		state = "closed"
 		sendBuffer.length = 0
 		ws.close(code, reason)
 	}
 
+	function on(event: "binary", handler: (data: ArrayBuffer) => void): void
 	function on(event: "close", handler: (code: number, reason: string) => void): void
 	function on(event: "error", handler: (error: unknown) => void): void
 	function on(event: "message", handler: (data: string) => void): void
 	function on(event: "open", handler: () => void): void
 	function on(event: string, handler: (...args: never[]) => void): void {
+		if (!EVENTS.has(event)) return
 		let wrapped: EventListener
 		switch (event) {
 			case "message":
-				wrapped = (e: Event) => (handler as (data: string) => void)((e as MessageEvent).data)
+				wrapped = (e: Event) => {
+					const data = (e as MessageEvent).data
+					if (typeof data === "string") (handler as (data: string) => void)(data)
+				}
+				break
+			case "binary":
+				wrapped = (e: Event) => {
+					const data = (e as MessageEvent).data
+					if (data instanceof ArrayBuffer) (handler as (data: ArrayBuffer) => void)(data)
+				}
 				break
 			case "open":
 				wrapped = () => (handler as () => void)()
@@ -57,40 +84,49 @@ export function createTypedWebSocket(
 				wrapped = (e: Event) =>
 					(handler as (code: number, reason: string) => void)((e as CloseEvent).code, (e as CloseEvent).reason)
 				break
-			case "error":
+			default:
 				wrapped = (e: Event) => (handler as (error: unknown) => void)(e)
 				break
-			default:
-				return
 		}
-		listenerMap.set(handler, wrapped)
-		ws.addEventListener(event, wrapped)
+		let byHandler = listeners.get(event)
+		if (byHandler === undefined) {
+			byHandler = new WeakMap()
+			listeners.set(event, byHandler)
+		}
+		const previous = byHandler.get(handler)
+		if (previous) ws.removeEventListener(event === "binary" ? "message" : event, previous)
+		byHandler.set(handler, wrapped)
+		ws.addEventListener(event === "binary" ? "message" : event, wrapped)
 	}
 
 	function off(event: string, handler: (...args: never[]) => void): void {
-		const wrapped = listenerMap.get(handler)
+		const byHandler = listeners.get(event)
+		const wrapped = byHandler?.get(handler)
 		if (wrapped) {
-			ws.removeEventListener(event, wrapped)
-			listenerMap.delete(handler)
+			ws.removeEventListener(event === "binary" ? "message" : event, wrapped)
+			byHandler?.delete(handler)
 		}
 	}
 
-	function toWsData(data: ArrayBuffer | ArrayBufferView | string): string | Uint8Array<ArrayBuffer> {
+	function toPayload(data: ArrayBuffer | ArrayBufferView | Blob | object | string): Payload {
 		if (typeof data === "string") return data
-		const view =
-			data instanceof ArrayBuffer ? new Uint8Array(data) : new Uint8Array(data.buffer, data.byteOffset, data.byteLength)
-		const copy = new Uint8Array(view.byteLength)
-		copy.set(view)
-		return copy
+		if (typeof Blob !== "undefined" && data instanceof Blob) return data
+		if (data instanceof ArrayBuffer || ArrayBuffer.isView(data)) {
+			const view =
+				data instanceof ArrayBuffer
+					? new Uint8Array(data)
+					: new Uint8Array(data.buffer, data.byteOffset, data.byteLength)
+			const copy = new Uint8Array(view.byteLength)
+			copy.set(view)
+			return copy
+		}
+		return JSON.stringify(data)
 	}
 
-	function send(data: ArrayBuffer | ArrayBufferView | object | string) {
-		const payload =
-			typeof data === "string" || data instanceof ArrayBuffer || ArrayBuffer.isView(data)
-				? toWsData(data)
-				: JSON.stringify(data)
-
-		if (buffering) {
+	function send(data: ArrayBuffer | ArrayBufferView | Blob | object | string) {
+		if (state === "closed") return
+		const payload = toPayload(data)
+		if (state === "connecting") {
 			sendBuffer.push(payload)
 		} else {
 			ws.send(payload)

package/src/client-go/errors.go

@@ -6,6 +6,9 @@ import (
 	"encoding/json"
 	"fmt"
 	"net/http"
+	"strings"
+	"unicode"
+	"unicode/utf8"
 )
 
 // APIError is the interface implemented by all SDK error types.
@@ -155,37 +158,37 @@ type StatusErrorMeta struct {
 
 var statusErrorMap = map[int]func(status int, body []byte, data any, resp *http.Response) APIError{
 	400: func(s int, b []byte, d any, r *http.Response) APIError {
-		return &BadRequestError{Body: b, Data: d, Response: r, Message: string(b)}
+		return &BadRequestError{Body: b, Data: d, Response: r, Message: errorMessage(b, d)}
 	},
 	401: func(s int, b []byte, d any, r *http.Response) APIError {
-		return &UnauthorizedError{Body: b, Data: d, Response: r, Message: string(b)}
+		return &UnauthorizedError{Body: b, Data: d, Response: r, Message: errorMessage(b, d)}
 	},
 	403: func(s int, b []byte, d any, r *http.Response) APIError {
-		return &ForbiddenError{Body: b, Data: d, Response: r, Message: string(b)}
+		return &ForbiddenError{Body: b, Data: d, Response: r, Message: errorMessage(b, d)}
 	},
 	404: func(s int, b []byte, d any, r *http.Response) APIError {
-		return &NotFoundError{Body: b, Data: d, Response: r, Message: string(b)}
+		return &NotFoundError{Body: b, Data: d, Response: r, Message: errorMessage(b, d)}
 	},
 	409: func(s int, b []byte, d any, r *http.Response) APIError {
-		return &ConflictError{Body: b, Data: d, Response: r, Message: string(b)}
+		return &ConflictError{Body: b, Data: d, Response: r, Message: errorMessage(b, d)}
 	},
 	422: func(s int, b []byte, d any, r *http.Response) APIError {
-		return &UnprocessableEntityError{Body: b, Data: d, Response: r, Message: string(b)}
+		return &UnprocessableEntityError{Body: b, Data: d, Response: r, Message: errorMessage(b, d)}
 	},
 	429: func(s int, b []byte, d any, r *http.Response) APIError {
-		return &RateLimitError{Body: b, Data: d, Response: r, Message: string(b)}
+		return &RateLimitError{Body: b, Data: d, Response: r, Message: errorMessage(b, d)}
 	},
 	500: func(s int, b []byte, d any, r *http.Response) APIError {
-		return &InternalServerError{Body: b, Data: d, Response: r, Message: string(b)}
+		return &InternalServerError{Body: b, Data: d, Response: r, Message: errorMessage(b, d)}
 	},
 	502: func(s int, b []byte, d any, r *http.Response) APIError {
-		return &BadGatewayError{Body: b, Data: d, Response: r, Message: string(b)}
+		return &BadGatewayError{Body: b, Data: d, Response: r, Message: errorMessage(b, d)}
 	},
 	503: func(s int, b []byte, d any, r *http.Response) APIError {
-		return &ServiceUnavailableError{Body: b, Data: d, Response: r, Message: string(b)}
+		return &ServiceUnavailableError{Body: b, Data: d, Response: r, Message: errorMessage(b, d)}
 	},
 	504: func(s int, b []byte, d any, r *http.Response) APIError {
-		return &GatewayTimeoutError{Body: b, Data: d, Response: r, Message: string(b)}
+		return &GatewayTimeoutError{Body: b, Data: d, Response: r, Message: errorMessage(b, d)}
 	},
 }
 
@@ -203,5 +206,31 @@ func raiseForStatus(resp *http.Response, body []byte) error {
 	if fn, ok := statusErrorMap[resp.StatusCode]; ok {
 		return fn(resp.StatusCode, body, data, resp)
 	}
-	return &StatusError{StatusCode: resp.StatusCode, Body: body, Data: data, Response: resp, Message: string(body)}
+	return &StatusError{StatusCode: resp.StatusCode, Body: body, Data: data, Response: resp, Message: errorMessage(body, data)}
+}
+
+// errorMessage is the server's `message` field when the body is a JSON object
+// carrying one, else the body text. Control characters are dropped and the
+// result is capped, so a hostile server cannot fill logs or drive a terminal.
+func errorMessage(body []byte, data any) string {
+	text := string(body)
+	if m, ok := data.(map[string]any); ok {
+		if msg, ok := m["message"].(string); ok {
+			text = msg
+		}
+	}
+	var b strings.Builder
+	n := 0
+	for _, r := range text {
+		if n >= maxErrorMessageRunes {
+			b.WriteString("…")
+			break
+		}
+		if r == utf8.RuneError || unicode.IsControl(r) {
+			continue
+		}
+		b.WriteRune(r)
+		n++
+	}
+	return b.String()
 }

package/src/client-go/export.go

@@ -0,0 +1,44 @@
+// Code generated by honey. DO NOT EDIT.
+
+package sdk
+
+import (
+	"context"
+	"iter"
+	"net/http"
+)
+
+// The Honey* functions expose the SDK's URL, SSE and error handling to the
+// generated CLI, so both send byte-identical requests.
+
+// HoneyExpandPath fills `{name}` placeholders with escaped values and rejects
+// "", "." and "..".
+func HoneyExpandPath(template string, params map[string]string) (string, error) {
+	return expandPath(template, params)
+}
+
+// HoneyBuildURL joins base and an escaped path (keeping the base path) and
+// appends the query pairs in order.
+func HoneyBuildURL(baseURL, path string, query [][2]string) (string, error) {
+	q := make(queryList, 0, len(query))
+	for _, p := range query {
+		q = append(q, queryPair{key: p[0], value: p[1]})
+	}
+	return buildURL(baseURL, path, q)
+}
+
+// HoneyParseSSEStream yields the events of an SSE response and closes its body.
+func HoneyParseSSEStream(ctx context.Context, resp *http.Response) iter.Seq2[SSEEvent, error] {
+	return parseSSEStream(ctx, resp)
+}
+
+// HoneyRaiseForStatus returns the typed error for a non-2xx response, or nil.
+func HoneyRaiseForStatus(resp *http.Response, body []byte) error {
+	return raiseForStatus(resp, body)
+}
+
+// HoneyFormatQueryValue renders a query or header value the way every SDK
+// language does.
+func HoneyFormatQueryValue(v any) string {
+	return formatQueryValue(v)
+}

package/src/client-go/invalidation.go

@@ -3,16 +3,17 @@
 package sdk
 
 import (
+	"container/list"
 	"fmt"
-	"net/url"
 	"regexp"
 	"strings"
 	"sync"
 	"time"
 )
 
-/* placeholderRe matches `{name}` and `:name` placeholders. */
-var placeholderRe = regexp.MustCompile(`\{([a-zA-Z_][a-zA-Z0-9_]*)\}|:([a-zA-Z_][a-zA-Z0-9_]*)`)
+/* placeholderRe matches `{name}` (any name without braces or slashes) and a
+ * `:name` segment. A colon inside a segment (`/ops/1:cancel`) is literal. */
+var placeholderRe = regexp.MustCompile(`\{([^{}/]+)\}|(^|/):([a-zA-Z_][a-zA-Z0-9_]*)`)
 
 /* patternRegexCache caches compiled placeholder→`[^/]+` regexps per pattern key. */
 var patternRegexCache sync.Map /* map[string]*regexp.Regexp */
@@ -24,6 +25,8 @@ type staleEntry struct {
 	by    []string
 	seq   uint64
 	until time.Time
+	/* position in the tracker's LRU list */
+	elem *list.Element
 }
 
 // RequestMeta is the per-request invalidation snapshot consumers see on hook
@@ -44,7 +47,11 @@ func compilePattern(pattern string) *regexp.Regexp {
 	b.WriteByte('^')
 	last := 0
 	for _, m := range matches {
-		b.WriteString(regexp.QuoteMeta(pattern[last:m[0]]))
+		start := m[0]
+		if pattern[start] == '/' {
+			start++ /* keep the segment slash literal */
+		}
+		b.WriteString(regexp.QuoteMeta(pattern[last:start]))
 		b.WriteString(`[^/]+`)
 		last = m[1]
 	}
@@ -78,8 +85,10 @@ func interpolatePath(template string, params map[string]string) (string, error)
 	out := placeholderRe.ReplaceAllStringFunc(template, func(match string) string {
 		groups := placeholderRe.FindStringSubmatch(match)
 		key := groups[1]
+		prefix := ""
 		if key == "" {
-			key = groups[2]
+			prefix = groups[2]
+			key = groups[3]
 		}
 		val, ok := params[key]
 		if !ok {
@@ -88,7 +97,7 @@ func interpolatePath(template string, params map[string]string) (string, error)
 			}
 			return match
 		}
-		return url.PathEscape(val)
+		return prefix + escapePathSegment(val)
 	})
 	if missing != "" {
 		return "", fmt.Errorf("interpolatePath: missing path param %q", missing)
@@ -98,8 +107,8 @@ func interpolatePath(template string, params map[string]string) (string, error)
 
 // resolveInvalidationTargetsForMutation expands templated `METHOD /path/{x}`
 // invalidation entries to concrete `METHOD /path/abc` selectors using params.
-// Pattern-only entries (no params provided) pass through; entries whose
-// placeholders cannot be resolved are dropped.
+// An entry whose placeholders cannot all be resolved stays a pattern, so it
+// marks every instance stale (TS parity).
 func resolveInvalidationTargetsForMutation(targets []string, params map[string]string) []string {
 	out := make([]string, 0, len(targets))
 	for _, entry := range targets {
@@ -116,6 +125,7 @@ func resolveInvalidationTargetsForMutation(targets []string, params map[string]s
 		}
 		concrete, err := interpolatePath(template, params)
 		if err != nil {
+			out = append(out, entry)
 			continue
 		}
 		out = append(out, method+" "+concrete)
@@ -126,11 +136,14 @@ func resolveInvalidationTargetsForMutation(targets []string, params map[string]s
 // StaleTracker tracks invalidation state per `METHOD /path` selector with TS-
 // parity semantics: exact-key + pattern-key two-tier lookup, TTL stale window,
 // LRU eviction at cap, monotonic seq for clear-after-mutate ordering.
-// All public methods are safe for concurrent use.
+// All public methods are safe for concurrent use. A lookup costs one map read plus a scan of
+// the pattern keys of its method; touch and eviction are O(1).
 type StaleTracker struct {
-	mu         sync.Mutex
-	entries    map[string]*staleEntry
-	order      []string /* insertion order; oldest at index 0 */
+	mu      sync.Mutex
+	entries map[string]*staleEntry
+	order   *list.List /* of string keys; oldest at the front */
+	/* method → keys whose path still holds placeholders */
+	patterns   map[string]map[string]struct{}
 	enabled    bool
 	staleTime  time.Duration
 	maxEntries int
@@ -141,7 +154,7 @@ type StaleTracker struct {
 // NewStaleTracker constructs a tracker from an InvalidationConfig.
 // Tracker is disabled (cheap no-op) when cfg is nil or StaleTime ≤ 0.
 func NewStaleTracker(cfg *InvalidationConfig) *StaleTracker {
-	t := &StaleTracker{entries: map[string]*staleEntry{}}
+	t := &StaleTracker{entries: map[string]*staleEntry{}, order: list.New(), patterns: map[string]map[string]struct{}{}}
 	if cfg == nil || cfg.StaleTime <= 0 {
 		return t
 	}
@@ -203,21 +216,11 @@ func (t *StaleTracker) ClearStale(concreteSelector, concretePath, method string,
 		t.deleteLocked(concreteSelector)
 	}
 	toDelete := make([]string, 0)
-	for key, entry := range t.entries {
-		if entry.seq > seqSnapshot {
+	for key := range t.patterns[method] {
+		if t.entries[key].seq > seqSnapshot {
 			continue
 		}
-		if !strings.Contains(key, "{") && !strings.Contains(key, ":") {
-			continue
-		}
-		spaceIdx := strings.IndexByte(key, ' ')
-		if spaceIdx == -1 {
-			continue
-		}
-		if key[:spaceIdx] != method {
-			continue
-		}
-		if pathMatchesPattern(concretePath, key[spaceIdx+1:]) {
+		if pathMatchesPattern(concretePath, key[strings.IndexByte(key, ' ')+1:]) {
 			toDelete = append(toDelete, key)
 		}
 	}
@@ -278,29 +281,34 @@ func (t *StaleTracker) upsertLocked(key string, until time.Time, seq uint64, mut
 	if mutationSelector != "" {
 		by = append(by, mutationSelector)
 	}
-	t.entries[key] = &staleEntry{by: by, seq: seq, until: until}
-	t.order = append(t.order, key)
+	t.entries[key] = &staleEntry{by: by, elem: t.order.PushBack(key), seq: seq, until: until}
+	if method, path, ok := strings.Cut(key, " "); ok && pathHasPlaceholders(path) {
+		if t.patterns[method] == nil {
+			t.patterns[method] = map[string]struct{}{}
+		}
+		t.patterns[method][key] = struct{}{}
+	}
 }
 
 func (t *StaleTracker) touchOrderLocked(key string) {
-	for i, k := range t.order {
-		if k == key {
-			t.order = append(t.order[:i], t.order[i+1:]...)
-			break
-		}
+	if entry, ok := t.entries[key]; ok {
+		t.order.MoveToBack(entry.elem)
 	}
-	t.order = append(t.order, key)
 }
 
 func (t *StaleTracker) deleteLocked(key string) {
-	if _, ok := t.entries[key]; !ok {
+	entry, ok := t.entries[key]
+	if !ok {
 		return
 	}
 	delete(t.entries, key)
-	for i, k := range t.order {
-		if k == key {
-			t.order = append(t.order[:i], t.order[i+1:]...)
-			return
+	t.order.Remove(entry.elem)
+	if method, _, ok := strings.Cut(key, " "); ok {
+		if bucket := t.patterns[method]; bucket != nil {
+			delete(bucket, key)
+			if len(bucket) == 0 {
+				delete(t.patterns, method)
+			}
 		}
 	}
 }
@@ -315,7 +323,8 @@ func (t *StaleTracker) lookupLocked(concreteSelector, concretePath, method strin
 		}
 	}
 	expired := make([]string, 0)
-	for key, entry := range t.entries {
+	for key := range t.patterns[method] {
+		entry := t.entries[key]
 		if !entry.until.After(now) {
 			expired = append(expired, key)
 			continue
@@ -323,17 +332,7 @@ func (t *StaleTracker) lookupLocked(concreteSelector, concretePath, method strin
 		if key == concreteSelector {
 			continue
 		}
-		if !strings.Contains(key, "{") && !strings.Contains(key, ":") {
-			continue
-		}
-		spaceIdx := strings.IndexByte(key, ' ')
-		if spaceIdx == -1 {
-			continue
-		}
-		if key[:spaceIdx] != method {
-			continue
-		}
-		if pathMatchesPattern(concretePath, key[spaceIdx+1:]) {
+		if pathMatchesPattern(concretePath, key[strings.IndexByte(key, ' ')+1:]) {
 			allBy = append(allBy, entry.by...)
 		}
 	}
@@ -366,8 +365,7 @@ func (t *StaleTracker) enforceCapacityLocked() {
 	if target < 1 {
 		target = 1
 	}
-	for len(t.entries) > target && len(t.order) > 0 {
-		oldest := t.order[0]
-		t.deleteLocked(oldest)
+	for len(t.entries) > target && t.order.Len() > 0 {
+		t.deleteLocked(t.order.Front().Value.(string))
 	}
 }

package/src/client-go/nullable.go

@@ -0,0 +1,62 @@
+// Code generated by honey. DO NOT EDIT.
+
+package sdk
+
+import (
+	"bytes"
+	"encoding/json"
+)
+
+// Nullable is an optional field that may also be null. Its zero value is "absent": the key is
+// left out of the request (the field carries `omitzero`). NullOf sends an explicit null, Some a
+// value. Decoding sets it from the response: absent stays absent, null becomes null.
+type Nullable[T any] struct {
+	value T
+	set   bool
+	null  bool
+}
+
+// Some is a present, non-null value.
+func Some[T any](v T) Nullable[T] {
+	return Nullable[T]{value: v, set: true}
+}
+
+// NullOf is an explicit null.
+func NullOf[T any]() Nullable[T] {
+	return Nullable[T]{set: true, null: true}
+}
+
+// IsZero reports an absent field; encoding/json leaves it out under `omitzero`.
+func (n Nullable[T]) IsZero() bool {
+	return !n.set
+}
+
+// IsNull reports an explicit null.
+func (n Nullable[T]) IsNull() bool {
+	return n.set && n.null
+}
+
+// Get returns the value and whether there is one (false for absent and for null).
+func (n Nullable[T]) Get() (T, bool) {
+	return n.value, n.set && !n.null
+}
+
+func (n Nullable[T]) MarshalJSON() ([]byte, error) {
+	if !n.set || n.null {
+		return []byte("null"), nil
+	}
+	return json.Marshal(n.value)
+}
+
+func (n *Nullable[T]) UnmarshalJSON(data []byte) error {
+	if bytes.Equal(bytes.TrimSpace(data), []byte("null")) {
+		*n = NullOf[T]()
+		return nil
+	}
+	var v T
+	if err := json.Unmarshal(data, &v); err != nil {
+		return err
+	}
+	*n = Some(v)
+	return nil
+}