93 lines
4.4 KiB
Markdown
93 lines
4.4 KiB
Markdown
# 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 & <tricks>",
|
|
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 & <tricks>","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.
|