On this page

Response Helpers

MuxMaster provides a small set of functions that write complete HTTP responses in one call. JSON, XML and Text set the Content-Type header (replacing any value already set), call WriteHeader, and write the body; a code of 0 means 200 OK.

Functions

JSON

func JSON(w http.ResponseWriter, code int, v any) error

Marshals v to JSON, sets Content-Type: application/json; charset=utf-8, writes the status code, and writes the body.

// Object
muxmaster.JSON(w, http.StatusOK, user)

// Slice
muxmaster.JSON(w, http.StatusOK, users)

// Inline map
muxmaster.JSON(w, http.StatusCreated, map[string]any{
    "id":   42,
    "name": "Alice",
})

// Error response
muxmaster.JSON(w, http.StatusNotFound, map[string]string{
    "error": "user not found",
})

Passing 0 as the code defaults to 200 OK.

Returns the marshalling or write error; it does not write anything if marshalling fails.


XML

func XML(w http.ResponseWriter, code int, v any) error

Marshals v to XML with encoding/xml, sets Content-Type: application/xml; charset=utf-8, and writes the response. Like JSON, it returns the marshalling or write error and writes nothing if marshalling fails.

type User struct {
    XMLName xml.Name `xml:"user"`
    ID      int      `xml:"id,attr"`
    Name    string   `xml:"name"`
}

muxmaster.XML(w, http.StatusOK, User{ID: 42, Name: "Alice"})

Text

func Text(w http.ResponseWriter, code int, s string) error

Writes s as plain text with Content-Type: text/plain; charset=utf-8. It always returns nil; the error result exists for symmetry with JSON and XML.

muxmaster.Text(w, http.StatusOK, "pong")
muxmaster.Text(w, http.StatusOK, fmt.Sprintf("hello, %s", name))

Redirect

func Redirect(w http.ResponseWriter, r *http.Request, code int, url string)

Issues an HTTP redirect with the given 3xx status code. It delegates to http.Redirect, so it does not apply the backslash and control-byte encoding of the router's own redirects. Never pass an unvalidated, user-supplied URL: that creates an open redirect.

muxmaster.Redirect(w, r, http.StatusMovedPermanently, "/new-path")
muxmaster.Redirect(w, r, http.StatusFound, "https://example.com")

NoContent

func NoContent(w http.ResponseWriter)

Writes a 204 No Content response with no body.

mux.DELETE("/users/:id", func(w http.ResponseWriter, r *http.Request) {
    db.DeleteUser(muxmaster.PathParam(r, "id"))
    muxmaster.NoContent(w)
})

Using Helpers with HandlerFuncE

The helpers return errors, which makes them natural to use in error-returning handlers:

mux.GETE("/users/:id", func(w http.ResponseWriter, r *http.Request) error {
    id, err := muxmaster.ParamsFromContext(r.Context()).Int("id")
    if err != nil {
        return muxmaster.Error(http.StatusBadRequest, err)
    }
    user, err := db.FindUser(id)
    if err != nil {
        return muxmaster.Error(http.StatusNotFound, errors.New("not found"))
    }
    return muxmaster.JSON(w, http.StatusOK, user)
})

If JSON fails (e.g. the value cannot be marshalled), the error is returned to the ErrorHandler.


Using Standard encoding/json Directly

For streaming or large responses where you want more control, use encoding/json directly:

mux.GET("/users", func(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json; charset=utf-8")
    w.WriteHeader(http.StatusOK)
    if err := json.NewEncoder(w).Encode(users); err != nil {
        log.Printf("encode error: %v", err)
    }
})

The helpers are a convenience for the common case; they do not restrict your options.


See Also

Common questions

How do I write a JSON response with MuxMaster?

Call muxmaster.JSON(w, code, v), which marshals v, sets Content-Type: application/json; charset=utf-8, writes the status code, and writes the body.

It returns the marshalling or write error and writes nothing if marshalling fails. A code of 0 means 200 OK.

Which response helpers does MuxMaster provide?

MuxMaster provides five response helpers: JSON, XML, Text, Redirect, and NoContent.

JSON, XML, and Text return an error, so they can be returned directly from a HandlerFuncE. Text always returns nil.

Is muxmaster.Redirect safe to use with a URL from the request?

No: muxmaster.Redirect delegates to http.Redirect and does not validate the target, so passing an unvalidated, user-supplied URL creates an open redirect.

It also does not apply the backslash and control-byte encoding that the router uses for its own automatic redirects.

Upstream source

This page mirrors docs/response-helpers.md at the v1.3.0 tag. The behaviour it describes is implemented in response.go.