Documentation
¶
Overview ¶
Package apihelpers carries the low-level HTTP/db utility functions shared by airlock's two HTTP surfaces:
- api/ — operator-facing /api/v1, /auth, /webhooks (user JWT).
- agentapi/ — agent-internal /api/agent (agent JWT).
router.go (in api/) wires both surfaces, so api imports agentapi. To keep the dep graph acyclic, anything both packages need lives here as a leaf: protobuf + JSON readers/writers, pgtype helpers, UUID parsing. No trigger / service / dbq imports — pure plumbing.
Index ¶
- Constants
- Variables
- func DecodeProto(r *http.Request, msg proto.Message) error
- func ParseOptionalProviderID(s string) (pgtype.UUID, error)
- func ParseUUID(s string) (uuid.UUID, error)
- func PgInt4(n int32) pgtype.Int4
- func PgText(s string) pgtype.Text
- func PgUUID(u pgtype.UUID) uuid.UUID
- func ReadJSON(r *http.Request, v any) error
- func ToPgUUID(u uuid.UUID) pgtype.UUID
- func TruncateUTF8(s string, maxLen int) string
- func WriteError(w http.ResponseWriter, status int, msg string)
- func WriteJSON(w http.ResponseWriter, status int, v any)
- func WriteJSONError(w http.ResponseWriter, status int, msg string)
- func WriteProto(w http.ResponseWriter, status int, msg proto.Message)
Constants ¶
const MaxRequestBodyBytes int64 = 4 << 20
Variables ¶
var ErrRequestBodyTooLarge = errors.New("request body too large")
var ProtoMarshal = protojson.MarshalOptions{ UseProtoNames: false, EmitUnpopulated: true, }
ProtoMarshal is the shared protojson encoder. UseProtoNames=false emits camelCase (matching the frontend convention) and EmitUnpopulated=true keeps zero-valued scalars on the wire so the frontend doesn't have to defensively check undefined vs. zero.
var ProtoUnmarshal = protojson.UnmarshalOptions{ DiscardUnknown: true, }
ProtoUnmarshal is the shared protojson decoder. DiscardUnknown is on so a newer frontend pushing fields a stale backend doesn't understand isn't a 400.
Functions ¶
func DecodeProto ¶
DecodeProto reads the request body and parses it via the shared ProtoUnmarshal options. Closes r.Body when done.
func ParseOptionalProviderID ¶
ParseOptionalProviderID accepts an empty string (returns invalid pgtype.UUID, no error) or a parseable UUID (returns Valid pgtype.UUID). Used by model-slot handlers where empty FK ⇄ "no provider bound for this slot".
func ParseUUID ¶
ParseUUID is a thin alias for uuid.Parse — exists for symmetry with the other helpers and so handlers don't import google/uuid just for one call.
func PgText ¶
PgText wraps a string in a pgtype.Text marked Valid. Use for INSERTs or UPDATEs against NULLABLE text columns where empty string is meaningful (e.g. a key with no comment).
func PgUUID ¶
PgUUID converts a pgtype.UUID to a google/uuid.UUID. Returns the zero UUID for an invalid pg value — callers that need to distinguish NULL from zero should check the Valid flag directly.
func TruncateUTF8 ¶
TruncateUTF8 clips s to at most maxLen *bytes*, never cutting in the middle of a UTF-8 sequence. A naive s[:maxLen] would leave a dangling lead byte (e.g. Cyrillic 0xd0 starts a 2-byte rune; slicing between the lead and continuation byte produces invalid UTF-8 that Postgres rejects with `invalid byte sequence for encoding "UTF8"`). Backs off to the previous rune boundary via utf8.RuneStart.
func WriteError ¶
func WriteError(w http.ResponseWriter, status int, msg string)
WriteError is the shared 4xx/5xx wire shape — an ErrorResponse proto with the given message, encoded the same way as any other response so the frontend's typed-error path handles it without a separate code branch.
func WriteJSON ¶
func WriteJSON(w http.ResponseWriter, status int, v any)
WriteJSON is the legacy non-proto response writer used by the /api/agent surface (where the agentsdk client speaks JSON, not proto) and by a couple of operator endpoints that predate the proto rollout.
func WriteJSONError ¶
func WriteJSONError(w http.ResponseWriter, status int, msg string)
WriteJSONError is WriteError's non-proto twin: a JSON {"error": msg} body. Used by handlers whose response shape is JSON throughout.
func WriteProto ¶
func WriteProto(w http.ResponseWriter, status int, msg proto.Message)
WriteProto serializes msg via ProtoMarshal and writes it as application/json. Errors from Marshal are swallowed — for proto types we control, they don't fail.
Types ¶
This section is empty.
Source Files