feat: backend service

backend/internal/engineclient/errors.go

@@ -0,0 +1,43 @@
+// Package engineclient is the trusted-internal HTTP client `internal/runtime`
+// uses to talk to a running `galaxy-game` engine container. The engine
+// contract is the OpenAPI document shipped with the engine module
+// (`galaxy/game/openapi.yaml`); this package reuses the existing typed
+// DTOs in `pkg/model/{rest,order,report}` rather than introducing its
+// own request/response types.
+//
+// The engine endpoint URL is per-call: the runtime stores it on
+// `runtime_records.engine_endpoint` (the value the dockerclient adapter
+// returns from Run). The client therefore does not bind a base URL at
+// construction time — only the per-call timeouts are wired through
+// `Config`.
+//
+// Error model:
+//
+// - ErrEngineUnreachable — network failure, 5xx, or timeout. The
+// caller transitions the runtime record to `engine_unreachable`
+// and re-tries on the next snapshot tick.
+// - ErrEngineValidation — engine rejected the request (HTTP 4xx).
+// The caller surfaces the engine's body verbatim through to the
+// user.
+// - ErrEngineProtocolViolation — engine returned an empty body or a
+// malformed JSON response on a path that requires one.
+package engineclient
+
+import "errors"
+
+var (
+	// ErrEngineUnreachable means the engine call failed because of a
+	// transport error (network, DNS, connect refused, timeout, 5xx).
+	// The implementation callers map this to a runtime status of
+	// `engine_unreachable` after a snapshot read.
+	ErrEngineUnreachable = errors.New("engineclient: engine unreachable")
+
+	// ErrEngineValidation means the engine returned a 4xx response.
+	// Callers forward the engine body so end users see the engine's
+	// per-command error reason verbatim.
+	ErrEngineValidation = errors.New("engineclient: engine validation failed")
+
+	// ErrEngineProtocolViolation means the engine returned an empty or
+	// malformed body on a path that contractually requires one.
+	ErrEngineProtocolViolation = errors.New("engineclient: engine protocol violation")
+)