# wire JSON response helpers and value types that keep API bodies byte-compatible with a PHP (WinterCMS/Laravel) backend. `import "git.golem15.com/golem15/summercms/modules/wire"` **Name:** What goes over the wire; it keeps response bodies byte-for-byte the same as the PHP backend's. ## Overview `wire` is the lowest layer of the HTTP stack: it decides how a Go value becomes response bytes. Its helpers reproduce what `json_encode` and Carbon produce in a WinterCMS or Laravel app (unescaped HTML characters, no trailing newline, `+00:00` timestamps, nullable booleans, `[]` rather than `null` for empty lists), so an endpoint ported from PHP returns the same body its existing clients already parse. [surf](../surf/README.md) uses it for the opaque 500 response of its panic recovery, and application handlers use it directly for their JSON responses. ## Role in the framework A dependency-free leaf for response shapes. `surf` and `lighthouse` use it, and so do plugin controllers. It is separate so every handler produces the same JSON as the PHP backend being replaced, byte for byte. Use cases: - Return paginated lists and error envelopes in the shape an existing frontend expects. - Encode timestamps, nullable booleans and empty lists the way Laravel serializes them. - Port endpoints one at a time without the frontend noticing the backend changed. ## Features - `wire.WriteJSON` encodes a value with HTML escaping disabled and without the trailing newline `encoding/json` adds, then sets `Content-Type: application/json` and the status code. If encoding fails, it writes the opaque 500 body instead of a partial response. - `wire.WriteOpaque500` writes a 500 response with the fixed body `{"error":true,"message":"Internal server error"}`, which reveals nothing about the failure. - `wire.Time` wraps `time.Time` and always marshals in UTC as `2006-01-02T15:04:05+00:00` (Carbon's form, never Go's `Z`). It unmarshals a timestamp with a numeric offset or an RFC 3339 `Z` timestamp, and turns `null` into the zero time. - `wire.TriBool` models a nullable boolean: when `wire.TriBool.Valid` is false it marshals as `null`, otherwise as `wire.TriBool.Value`. - `wire.Slice` returns a non-nil empty slice for a nil input, so optional lists marshal as `[]` instead of `null`. ## Usage ```go src=modules/wire/example_test.go#postJSON // postJSON is the response shape of one acme.blog post. type postJSON struct { ID uint `json:"id"` Title string `json:"title"` Tags []string `json:"tags"` Featured wire.TriBool `json:"featured"` Pinned wire.TriBool `json:"pinned"` PublishedAt wire.Time `json:"published_at"` } ``` ```go src=modules/wire/example_test.go#ExampleWriteJSON var tags []string // nil: the post has no tags warsaw := time.FixedZone("CEST", 2*60*60) body := postJSON{ ID: 1, Title: "Tips & ", Tags: wire.Slice(tags), Featured: wire.TriBool{}, Pinned: wire.TriBool{Value: true, Valid: true}, PublishedAt: wire.Time{Time: time.Date(2026, 9, 30, 14, 5, 0, 0, warsaw)}, } rec := httptest.NewRecorder() wire.WriteJSON(rec, http.StatusOK, map[string]any{"data": body}) fmt.Println(rec.Code, rec.Header().Get("Content-Type")) fmt.Printf("%s|\n", rec.Body.String()) rec = httptest.NewRecorder() wire.WriteOpaque500(rec) fmt.Println(rec.Code, rec.Body.String()) // Output: // 200 application/json // {"data":{"id":1,"title":"Tips & ","tags":[],"featured":null,"pinned":true,"published_at":"2026-09-30T12:05:00+00:00"}}| // 500 {"error":true,"message":"Internal server error"} ``` ## API reference | Identifier | Description | |------------|-------------| | `wire.WriteJSON` | Writes a JSON body with HTML escaping off and no trailing newline; falls back to the opaque 500 on an encoding error. | | `wire.WriteOpaque500` | Writes the fixed `{"error":true,"message":"Internal server error"}` 500 response. | | `wire.Time` | `time.Time` wrapper that marshals as UTC `+00:00` and reads both `+00:00` and `Z` forms. | | `wire.TriBool` | Nullable boolean: `wire.TriBool.Valid` false marshals `null`, otherwise `wire.TriBool.Value`. | | `wire.Slice` | Generic helper that turns a nil slice into an empty one so it marshals as `[]`. | ## Dependencies - SummerCMS modules: none. - Third-party: none. - Standard library: `bytes`, `encoding/json`, `net/http`, `time`. ## Testing ```sh go test ./modules/wire/... ``` The tests use `net/http/httptest` and need no external services.