feat: add Bind and built‑in decoders for JSON, XML, query, form, path, header

[qm012]

What

Add a generic request-binding API to sim:

• Decoder[T] / DecoderFunc[T]: pluggable interface for decoding an HTTP request into a *T
• Validator: optional post-decode validation hook, invoked automatically by Bind when implemented
• Bind[T](r, src): decodes the request with the given decoder and returns the decoded value or error
• Built-in decoders: BindJSON, BindXML, BindQuery, BindForm, BindPath, BindHeader
• JSON decoder options: UseNumber(), DisallowUnknownFields()
• BufferBody: buffers the request body, restores it for subsequent reads, and caches a copy in the context for repeated reads via BodyFromContext

Usage

JSON body with validation:

type createUser struct {
    Name  string `json:"name"`
    Email string `json:"email"`
}

func (u *createUser) Validate(ctx context.Context) error {
    if u.Email == "" {
        return errors.New("email required")
    }
    return nil
}

app.Post("/users", func(w http.ResponseWriter, r *http.Request) {
    u, err := sim.BindJSON[createUser](r, sim.DisallowUnknownFields())
    if err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }
    // use u.Name, u.Email ...
})

Query with default= and a map target:

type listQuery struct {
    Page  int `query:"page,default=1"`
    Limit int `query:"limit,default=20"`
}

app.Get("/users", func(w http.ResponseWriter, r *http.Request) {
    q, err := sim.BindQuery[listQuery](r)
    // ...
    all, err := sim.BindQuery[map[string][]string](r)
})

Path and header:

type userPath struct {
    ID int64 `path:"id"`
}

type authHeader struct {
    Token string `header:"Authorization"`
}

app.Get("/users/{id}", func(w http.ResponseWriter, r *http.Request) {
    p, err := sim.BindPath[userPath](r)
    h, err := sim.BindHeader[authHeader](r)
})

Multipart form with file upload:

type uploadForm struct {
    Title string                  `form:"title"`
    File  *multipart.FileHeader   `form:"file"`
}

app.Post("/upload", func(w http.ResponseWriter, r *http.Request) {
    f, err := sim.BindForm[uploadForm](r)
})

Repeated body reads via BufferBody:

func BufferBodyHandler(h http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		nr, err := sim.BufferBody(r)
		if err != nil {
			http.Error(w, err.Error(), http.StatusBadRequest)
			return
		}
		h.ServeHTTP(w, nr)
	})
}

Custom formats plug in through sim.Decoder[T] / sim.DecoderFunc[T] and are passed to sim.Bind.

[qm012]

related #42

[qm012]

/lgtm

[github-actions]

Merging this branch will increase overall coverage

Impacted Packages	Coverage Δ	🤖
github.com/qm012/sim	94.37% (+3.10%)	👍

---

Coverage by file

Changed files (no unit tests)

Changed File	Coverage Δ	Total	Covered	Missed	🤖
github.com/qm012/sim/binder.go	97.46% (+97.46%)	276 (+276)	269 (+269)	7 (+7)	🌟
github.com/qm012/sim/sim.go	0.00% (ø)	0	0	0

Please note that the "Total", "Covered", and "Missed" counts above refer to code statements instead of lines of code. The value in brackets refers to the test coverage of that file in the old version of the code.

Changed unit test files

• github.com/qm012/sim/binder_test.go
• github.com/qm012/sim/example_test.go