roamer

func ContextWithParsedData ¶

func ContextWithParsedData(ctx context.Context, data any) context.Context

ContextWithParsedData creates a new context containing the parsed data.

This function is used internally by roamer middleware (Middleware, SliceMiddleware) to store parsed request data in the context for downstream handlers to retrieve using ParsedDataFromContext.

Parameters:

• ctx: The parent context.
• data: The parsed data to store (typically a pointer to a struct or slice).

Returns:

• context.Context: A new context containing the parsed data.

func ContextWithParsingError ¶ added in v1.8.0

func ContextWithParsingError(ctx context.Context, err error) context.Context

ContextWithParsingError creates a new context containing a parsing error.

This function is used internally by roamer middleware to propagate parsing errors to downstream handlers. The error can be retrieved using ParsedDataFromContext, which will return it instead of the parsed data.

Parameters:

• ctx: The parent context.
• err: The parsing error that occurred.

Returns:

• context.Context: A new context containing the error.

func IsDecodeError ¶

func IsDecodeError(err error) (rerr.DecodeError, bool)

IsDecodeError checks if an error is a DecodeError from request body parsing. Useful for providing specific error handling for body decoding failures.

Example:

if err := roamer.Parse(req, &data); err != nil {
    if decodeErr, ok := roamer.IsDecodeError(err); ok {
        // Special handling for decode errors
        http.Error(w, "Invalid request format", http.StatusBadRequest)
        return
    }
    // Handle other errors
}

package main

import (
	"bytes"
	"fmt"
	"net/http"

	"github.com/slipros/roamer"
	"github.com/slipros/roamer/decoder"
)

// readCloser wraps a bytes.Buffer to implement io.ReadCloser
type readCloser struct {
	*bytes.Buffer
}

func (rc *readCloser) Close() error {
	return nil
}

func main() {
	// Define a structure
	type User struct {
		ID   int    `json:"id"`
		Name string `json:"name"`
	}

	// Create roamer with JSON decoder
	r := roamer.NewRoamer(
		roamer.WithDecoders(decoder.NewJSON()),
	)

	// Create request with invalid JSON body (malformed JSON)
	invalidJSON := `{invalid}` // Malformed JSON to cause parsing error
	req := &http.Request{
		Method: "POST",
		Header: http.Header{
			"Content-Type": {"application/json"},
		},
		Body:          &readCloser{bytes.NewBufferString(invalidJSON)},
		ContentLength: int64(len(invalidJSON)),
	}

	var user User
	err := r.Parse(req, &user)
	if err != nil {
		// Check if it's a decode error
		if decodeErr, isDecodeError := roamer.IsDecodeError(err); isDecodeError {
			fmt.Printf("Decode error occurred: %v\n", decodeErr)
			// Handle decode error specifically
			return
		}

		// Handle other types of errors
		fmt.Printf("Other error: %v\n", err)
		return
	}

	fmt.Printf("User parsed successfully: %+v\n", user)

}

Output:

Decode error occurred: decode `application/json` request body for `*roamer_test.User`: roamer_test.User.readFieldHash: expect ", but found i, error found in #2 byte of ...|{invalid}|..., bigger context ...|{invalid}|...

func IsSliceIterationError ¶

func IsSliceIterationError(err error) (rerr.SliceIterationError, bool)

IsSliceIterationError checks if an error occurred during slice iteration. Provides access to the specific index where the error occurred.

Example:

if err := processItems(items); err != nil {
    if iterErr, ok := roamer.IsSliceIterationError(err); ok {
        // Access problem index with iterErr.Index
        return fmt.Errorf("item %d invalid: %w", iterErr.Index, iterErr.Err)
    }
}

package main

import (
	"fmt"

	"github.com/slipros/roamer"
	"github.com/slipros/roamer/err"
)

func main() {
	// This example simulates a scenario where slice iteration might fail
	// In practice, this would occur during complex slice processing operations

	// Create a mock slice iteration error for demonstration
	originalErr := fmt.Errorf("validation failed")
	sliceErr := err.SliceIterationError{
		Err:   originalErr,
		Index: 2,
	}

	// Simulate checking the error
	var testErr error = sliceErr

	if iterErr, isSliceError := roamer.IsSliceIterationError(testErr); isSliceError {
		fmt.Printf("Slice iteration error at index %d: %v\n", iterErr.Index, iterErr.Err)
	} else {
		fmt.Printf("Not a slice iteration error: %v\n", testErr)
	}

}

Output:

Slice iteration error at index 2: validation failed

func Middleware ¶

func Middleware[T any](roamer *Roamer) func(next http.Handler) http.Handler

Middleware creates an HTTP middleware that parses requests into a specified type and stores the result in the request context for downstream handlers to retrieve.

The middleware parses the incoming HTTP request using the provided Roamer instance, stores the parsed data (or error) in the request context, and then calls the next handler in the chain. Downstream handlers can retrieve the parsed data using ParsedDataFromContext.

Type Parameter ¶

• T: The type to parse the request into. Must be a struct type.

Behavior ¶

• If roamer is nil, the middleware passes through without parsing
• On successful parsing, stores parsed data in context with ContextKeyParsedData
• On parsing error, stores error in context with ContextKeyParsingError
• Always calls the next handler, even if parsing fails (error handling is delegated)

Error Handling ¶

The middleware does NOT stop the request chain on parsing errors. Instead, it stores the error in the context and delegates error handling to downstream handlers. This allows handlers to decide how to respond to parsing errors.

Parameters:

• roamer: The Roamer instance to use for parsing. If nil, middleware is a no-op.

Returns:

• func(next http.Handler) http.Handler: A middleware function that wraps the next handler.

Example:

type UserRequest struct {
    ID   int    `query:"id"`
    Name string `json:"name"`
}

r := roamer.NewRoamer(
    roamer.WithDecoders(decoder.NewJSON()),
    roamer.WithParsers(parser.NewQuery()),
)

// Use with http.Handle
http.Handle("/users", roamer.Middleware[UserRequest](r)(
    http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        var data UserRequest
        if err := roamer.ParsedDataFromContext(r.Context(), &data); err != nil {
            http.Error(w, err.Error(), http.StatusBadRequest)
            return
        }
        fmt.Fprintf(w, "Hello, %s (ID: %d)!", data.Name, data.ID)
    }),
))

// Or with chi router
router := chi.NewRouter()
router.Use(roamer.Middleware[UserRequest](r))
router.Post("/users", func(w http.ResponseWriter, r *http.Request) {
    var data UserRequest
    if err := roamer.ParsedDataFromContext(r.Context(), &data); err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }
    // Process user...
})

package main

import (
	"fmt"
	"net/http"
	"net/url"

	"github.com/slipros/roamer"
	"github.com/slipros/roamer/parser"
)

func main() {
	type APIRequest struct {
		Action string `query:"action"`
		UserID int    `query:"user_id"`
	}

	// Create roamer instance
	r := roamer.NewRoamer(
		roamer.WithParsers(parser.NewQuery()),
	)

	// Create middleware
	middleware := roamer.Middleware[APIRequest](r)

	// Sample handler
	handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		var data APIRequest
		if err := roamer.ParsedDataFromContext(r.Context(), &data); err != nil {
			http.Error(w, err.Error(), http.StatusBadRequest)
			return
		}

		fmt.Printf("Action: %s, User ID: %d\n", data.Action, data.UserID)
		w.WriteHeader(http.StatusOK)
	})

	// Wrap handler with middleware
	wrappedHandler := middleware(handler)

	// Create test request
	req := &http.Request{
		Method: "GET",
		URL: &url.URL{
			RawQuery: "action=update&user_id=456",
		},
		Header: make(http.Header),
	}

	// Simulate request handling
	wrappedHandler.ServeHTTP(&mockResponseWriter{}, req)

}

type mockResponseWriter struct {
	statusCode int
}

func (m *mockResponseWriter) Header() http.Header {
	return make(http.Header)
}

func (m *mockResponseWriter) Write([]byte) (int, error) {
	return 0, nil
}

func (m *mockResponseWriter) WriteHeader(statusCode int) {
	m.statusCode = statusCode
}

Output:

Action: update, User ID: 456

func NewParseWithPool ¶ added in v1.16.0

func NewParseWithPool[T any](r *Roamer) func(req *http.Request, callback func(*T) error) error

NewParseWithPool creates a memory-efficient parser function that uses object pooling to reduce allocations when processing HTTP requests. This is particularly useful for high-throughput scenarios where creating new instances repeatedly would create unnecessary garbage collection pressure.

The returned function parses HTTP requests into instances of type T from a sync.Pool, passes the parsed instance to the callback function, and then returns it to the pool after zeroing its fields. This ensures memory reuse while preventing data leakage between requests.

Performance characteristics:

• Reduces heap allocations by reusing instances of type T
• Automatically zeros out fields before returning to pool
• Thread-safe for concurrent request processing
• Minimal overhead compared to direct parsing

Example:

type UserRequest struct {
    ID   int    `query:"id"`
    Name string `json:"name"`
}

r := roamer.NewRoamer(
    roamer.WithDecoders(decoder.NewJSON()),
    roamer.WithParsers(parser.NewQuery()),
)

// Create a pooled parser function
parseUser := roamer.NewParseWithPool[UserRequest](r)

// Use in HTTP handler
http.HandleFunc("/user", func(w http.ResponseWriter, req *http.Request) {
    err := parseUser(req, func(user *UserRequest) error {
        // Process the parsed user data
        // The user instance will be automatically returned to pool
        return processUser(user)
    })
    if err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }
})

Parameters:

• r: The configured Roamer instance to use for parsing requests.

Returns:

• A function that accepts an HTTP request and a callback function. The callback receives a pointer to the parsed data of type T. Returns an error if parsing fails or if the callback returns an error.

Notes:

• The callback function must not retain references to the parsed instance after returning, as it will be zeroed and returned to the pool.
• If you need to keep the data, copy it to a new instance within the callback.
• The pool grows dynamically based on concurrent usage patterns.

func Parse ¶ added in v1.14.0

func Parse[T any](r *Roamer, req *http.Request) (T, error)

Parse is a generic function that extracts data from an HTTP request into a value of type T. This is a convenience wrapper around the Roamer.Parse method that returns the parsed value directly instead of requiring a pointer parameter.

The function creates a zero value of type T, parses the request data into it, and returns both the result and any error that occurred during parsing.

Example:

type UserData struct {
    ID        int    `query:"id"`
    Name      string `json:"name"`
    UserAgent string `header:"User-Agent"`
}

// Parse request data directly into a value
userData, err := roamer.Parse[UserData](roamer, request)
if err != nil {
    return err
}
// Use userData...

Parameters:

• r: The configured Roamer instance to use for parsing.
• req: The HTTP request to parse data from.

Returns:

• T: The parsed data structure of the specified type.
• error: An error if parsing fails, or nil if successful.

package main

import (
	"fmt"
	"net/http"
	"net/url"

	"github.com/slipros/roamer"
	"github.com/slipros/roamer/parser"
)

func main() {
	// Define a structure
	type ProductRequest struct {
		Category string  `query:"category"`
		MinPrice float64 `query:"min_price"`
		MaxPrice float64 `query:"max_price"`
	}

	// Create roamer instance
	r := roamer.NewRoamer(
		roamer.WithParsers(parser.NewQuery()),
	)

	// Create request with query parameters
	req := &http.Request{
		Method: "GET",
		URL: &url.URL{
			RawQuery: "category=electronics&min_price=100.50&max_price=999.99",
		},
		Header: make(http.Header),
	}

	// Use generic Parse function
	product, err := roamer.Parse[ProductRequest](r, req)
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}

	fmt.Printf("Category: %s\n", product.Category)
	fmt.Printf("Price range: $%.2f - $%.2f\n", product.MinPrice, product.MaxPrice)

}

Output:

Category: electronics
Price range: $100.50 - $999.99

func ParsedDataFromContext ¶

func ParsedDataFromContext[T any](ctx context.Context, ptr *T) error

ParsedDataFromContext extracts parsed request data from a context into the provided pointer.

This function is typically used in HTTP handlers to retrieve data that was previously parsed and stored in the context by roamer middleware (see Middleware or SliceMiddleware).

Error Handling ¶

The function returns an error if:

• The pointer is nil (NilValue error)
• A parsing error occurred and is stored in the context
• No data of the expected type is found in the context (NoData error)

Type Safety ¶

The function uses generics to ensure type safety. The type parameter T must match the type used when storing data in the context, otherwise a NoData error is returned.

Parameters:

• ctx: The context containing the parsed data (typically from http.Request.Context()).
• ptr: A pointer to the destination variable where the data will be copied.

Returns:

• error: An error if retrieval fails, or nil if successful.

Example:

type UserRequest struct {
    ID   int    `query:"id"`
    Name string `json:"name"`
}

func MyHandler(w http.ResponseWriter, r *http.Request) {
    var userData UserRequest
    if err := roamer.ParsedDataFromContext(r.Context(), &userData); err != nil {
        if errors.Is(err, err.NoData) {
            http.Error(w, "No user data in context", http.StatusInternalServerError)
            return
        }
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }
    // Use userData...
    fmt.Fprintf(w, "Hello, %s!", userData.Name)
}

func SliceMiddleware ¶ added in v1.9.0

func SliceMiddleware[T any](roamer *Roamer) func(next http.Handler) http.Handler

SliceMiddleware creates an HTTP middleware that parses the request body into a slice of the specified type and stores the result in the request context.

This middleware is particularly useful for API endpoints that handle arrays of objects, such as batch operations, bulk updates, or list submissions. It parses the request body (typically JSON) into a slice and makes it available to downstream handlers via the context.

Type Parameter ¶

• T: The element type of the slice. The request body will be parsed into []T.

Behavior ¶

• If roamer is nil, the middleware passes through without parsing
• Parses the request body into a slice of type []T
• On success, stores the slice in context with ContextKeyParsedData
• On error, stores the error in context with ContextKeyParsingError
• Always calls the next handler (error handling is delegated)

Use Cases ¶

• Batch creation endpoints: POST /api/users/batch with [{...}, {...}, ...]
• Bulk update operations: PUT /api/products/bulk with array of products
• List submission forms: POST /api/tasks with array of task items

Parameters:

• roamer: The Roamer instance to use for parsing. If nil, middleware is a no-op.

Returns:

• func(next http.Handler) http.Handler: A middleware function that wraps the next handler.

Example:

type Product struct {
    ID    int     `json:"id"`
    Name  string  `json:"name"`
    Price float64 `json:"price"`
}

r := roamer.NewRoamer(roamer.WithDecoders(decoder.NewJSON()))

// Batch product creation endpoint
http.Handle("/products/batch", roamer.SliceMiddleware[Product](r)(
    http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        var products []Product
        if err := roamer.ParsedDataFromContext(r.Context(), &products); err != nil {
            http.Error(w, err.Error(), http.StatusBadRequest)
            return
        }

        // Validate and process the batch
        if len(products) == 0 {
            http.Error(w, "Empty product list", http.StatusBadRequest)
            return
        }

        for i, product := range products {
            // Process each product
            fmt.Printf("Processing product %d: %s\n", i, product.Name)
        }

        fmt.Fprintf(w, "Successfully processed %d products", len(products))
    }),
))

// Request body example:
// [
//   {"id": 1, "name": "Widget", "price": 9.99},
//   {"id": 2, "name": "Gadget", "price": 19.99}
// ]