// router.go — the API consumer of the registry (0001 §9). Every registered
// op is mounted on a stdlib ServeMux; input crosses through the shared
// codecs and validator, output leaves as JSON. The generated OpenAPI
// document is served from the same registry at /api/v1/openapi.json.
package api
import (
"craftdesign.group/quarry/internal/errlog"
"encoding/json"
"errors"
"fmt"
"log"
"mime"
"net/http"
"net/url"
"reflect"
"strings"
"craftdesign.group/quarry/internal/ops"
)
// Verify checks one repo credential pair against the capability the op
// requires. A nil Verify leaves every gated op open (single-user local
// serving); the composition root supplies the OLTP-backed implementation.
// need is the op's own ops.Auth, so one seam serves both the write ops
// (Token) and the administrative ones (Admin) without the router
// deciding what either means.
type Verify func(repo, user, password string, need ops.Auth) Decision
// Decision is what a credential check concluded. Three outcomes rather
// than a bool because two of them are not the same thing and the wire
// has distinct codes for them: a client told 401 retries with the same
// credentials forever, when what it needed to hear was that the
// credentials were fine and the capability was not.
type Decision int
const (
// Denied: absent or wrong credentials. 401, with a challenge.
Denied Decision = iota
// Insufficient: authenticated, but lacking the capability. 403, and
// deliberately WITHOUT a challenge — re-authenticating cannot help.
Insufficient
// Allowed.
Allowed
)
// Router mounts every op in r plus the OpenAPI document. version flows
// into the spec's info block. verify (optional) gates ops.Token ops
// with HTTP Basic against it.
func Router(r *ops.Registry, version string, verify ...Verify) (http.Handler, error) {
var v Verify
if len(verify) > 0 {
v = verify[0]
}
mux := http.NewServeMux()
for _, d := range r.All() {
mux.Handle(d.Method+" "+d.Pattern, opHandler(r, d, v))
}
spec, err := ops.Spec(r, "quarry", version)
if err != nil {
return nil, err
}
specJSON, err := json.MarshalIndent(spec, "", " ")
if err != nil {
return nil, err
}
mux.HandleFunc("GET /api/v1/openapi.json", func(w http.ResponseWriter, _ *http.Request) {
w.Header().Set("Content-Type", "application/json")
w.Write(specJSON)
})
// Unmatched API paths answer in the API's own dialect, never Go's
// plain-text default.
mux.HandleFunc("/api/", func(w http.ResponseWriter, _ *http.Request) {
writeError(w, http.StatusNotFound, errors.New("no such endpoint"))
})
return mux, nil
}
func opHandler(r *ops.Registry, d *ops.Descriptor, verify Verify) http.Handler {
wild := ops.Wildcards(d.Pattern)
return http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
// Resolve identity even for ANONYMOUS ops. A private repository
// is readable by the people with a role on it, and a read op
// that never looks at credentials cannot tell those people from
// strangers — so its owner would be locked out of their own
// repository.
if d.Auth == ops.Anonymous && verify != nil {
if user, pass, ok := req.BasicAuth(); ok && user != "" {
if verify(req.PathValue("repo"), user, pass, ops.Anonymous) == Allowed {
req = req.WithContext(ops.WithUser(req.Context(), user))
}
}
}
if d.Auth != ops.Anonymous && verify != nil {
user, pass, _ := req.BasicAuth()
switch verify(req.PathValue("repo"), user, pass, d.Auth) {
case Denied:
w.Header().Set("WWW-Authenticate", `Basic realm="quarry"`)
writeError(w, http.StatusUnauthorized, errors.New("authentication required"))
return
case Insufficient:
writeError(w, http.StatusForbidden,
errors.New("this account does not have the capability this request needs"))
return
}
req = req.WithContext(ops.WithUser(req.Context(), user))
}
in, err := decodeIn(req, d, wild)
if err != nil {
writeError(w, http.StatusBadRequest, err)
return
}
if err := ops.Validate(in); err != nil {
writeError(w, http.StatusBadRequest, err)
return
}
out, err := r.Invoke(req.Context(), d.Name, in)
if errors.Is(err, ops.ErrNotFound) {
writeError(w, http.StatusNotFound, err)
return
}
if errors.Is(err, ops.ErrInvalid) {
writeError(w, http.StatusBadRequest, err)
return
}
if errors.Is(err, ops.ErrUnavailable) {
writeError(w, http.StatusServiceUnavailable, err)
return
}
if err != nil {
// The real error goes to the log AND the journal; the public
// body never carries internals (subprocess invocations, SQL,
// paths). The journal is what makes "details are in the
// server log" a promise someone can actually collect on.
log.Printf("api: %s: %v", d.Name, err)
errlog.Default.Report("api", d.Name, err)
writeError(w, http.StatusInternalServerError, errors.New("internal error"))
return
}
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(out)
})
}
// decodeIn assembles the op's In struct from the request: query string
// (GET) or body (POST, form or JSON by content type), with path wildcards
// merged last so the routed path is always authoritative.
func decodeIn(req *http.Request, d *ops.Descriptor, wild []string) (any, error) {
inPtr := d.NewIn()
switch {
case d.Method == http.MethodGet:
if err := ops.DecodeValues(req.URL.Query(), inPtr); err != nil {
return nil, err
}
case isJSON(req):
if err := json.NewDecoder(req.Body).Decode(inPtr); err != nil {
return nil, fmt.Errorf("body: %w", err)
}
default:
if err := req.ParseForm(); err != nil {
return nil, fmt.Errorf("form: %w", err)
}
if err := ops.DecodeValues(req.PostForm, inPtr); err != nil {
return nil, err
}
}
if len(wild) > 0 {
pathVals := url.Values{}
for _, name := range wild {
pathVals.Set(name, req.PathValue(name))
}
if err := ops.OverlayValues(pathVals, inPtr); err != nil {
return nil, err
}
}
return deref(inPtr), nil
}
func deref(p any) any {
return reflect.ValueOf(p).Elem().Interface()
}
func isJSON(req *http.Request) bool {
ct, _, _ := mime.ParseMediaType(req.Header.Get("Content-Type"))
return strings.HasSuffix(ct, "/json") || strings.HasSuffix(ct, "+json")
}
func writeError(w http.ResponseWriter, code int, err error) {
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(code)
json.NewEncoder(w).Encode(map[string]string{"error": err.Error()})
}