Fuego Go API Framework

Fuego is compatible with all net/http middlewares, including those from popular libraries like chi and gorilla. You can use them to implement cross-cutting concerns such as logging, authentication, and CORS.

Middlewares can be applied at two distinct levels:

1. Route middlewares: Scoped to specific routes or groups of routes.
2. Global middlewares: Applied to every single request, including non-matching routes (essential for handling OPTIONS requests in CORS).

When using fuego.Group, you can pass route options that will be inherited by all routes registered within that group.

Note: The maintainers recommend using option.Group instead of group-level inheritance for a more composable approach.

package main

import (
	"github.com/go-fuego/fuego"
	"github.com/go-fuego/fuego/option"
)

func main() {
	s := fuego.NewServer()

	g := fuego.Group(s, "/pets",
		option.Summary("Pets operations"),
		option.Description("Operations about pets"),
		option.Tags("pets"),
	)

	fuego.Get(g, "/", func(c fuego.ContextNoBody) (string, error) {
		return "Hello, World!", nil
	})
}

To return custom error structures that Fuego can automatically transform into RFC 9457 compliant HTTP responses, implement the fuego.ErrorWithStatus interface. This interface requires an Error() string method and a StatusCode() int method.

When an error implements fuego.ErrorWithStatus, Fuego transforms it into a fuego.HTTPError. The resulting response format (JSON or XML) is determined by the client's Accept header.

type ErrorWithStatus interface {
	error
	StatusCode() int
}

Fuego is built around four primary components that manage the lifecycle of a request and the structure of your application:

• Engine: The core of Fuego. It manages the request/response lifecycle, holds the OpenAPI struct (including descriptions and OpenAPI utilities), and provides a centralized Error Handler.
• Server: The underlying net/http server used to listen for requests. It manages routing, route groups, and middleware.
• Adaptors: Integration layers that allow you to use Fuego with other web frameworks like Gin or Echo.
• Context: A generic-typed interface used within controllers. It represents the state that a user can access and modify during a request.

You can pass route options to fuego.NewServer using fuego.WithRouteOptions. These options will be inherited by every route in the server.

Note: The maintainers recommend using option.Group instead of server-level inheritance for a more composable approach.

package main

import (
	"github.com/go-fuego/fuego"
	"github.com/go-fuego/fuego/option"
)

func main() {
	s := fuego.NewServer(
		fuego.WithRouteOptions(
			option.Summary("Pets operations"),
			option.Description("Operations about pets"),
			option.Tags("pets"),
		),
	)

	fuego.Get(s, "/", func(c fuego.ContextNoBody) (string, error) {
		return "Hello, World!", nil
	})
}

Controllers are the primary way to handle requests and responses in Fuego. A controller is a function that receives a context and returns a response and an error. Fuego supports Content Negotiation, allowing a single controller to serve different content types based on the Accept header.

Fuego avoids reflection for high performance, relying instead on underlying libraries like net/http, encoding/json, or gin (if using fuegogin) for deserialization.

// Standard fuego controller
func MyController(c fuego.ContextWithBody[Body]) (MyResponse, error)

You can implement the fuego.InTransform and fuego.OutTransform interfaces on your request/response structs to perform custom data manipulation or validation.

• InTransform(context.Context) error: Called just before c.Body() returns the data. Use this to sanitize inputs (e.g., lowercase strings) or perform complex validation. If it returns an error, the request fails.
• OutTransform(context.Context) error: Called before the response is sent to the client. Use this to transform outgoing data (e.g., uppercase strings).

type MyInput struct {
	Name string `json:"name" validate:"required"`
}

// Will be called just before returning c.Body()
func (r *MyInput) InTransform(context.Context) error {
	r.Name = strings.ToLower(r.Name)

	if r.Name == "fuego" {
		return errors.New("fuego is not a valid name for this input")
	}

	return nil
}

The lifecycle of a request and response in Fuego follows this specific sequence:

1. Request Arrival: Payload (JSON/XML/etc.) is received.
2. Deserialization: Payload is unmarshaled into your request struct.
3. Input Transformation: InTransform is called on the struct (if implemented).
4. Validation: Standard validation is performed based on struct tags.
5. Controller Execution: Your controller is called with the transformed/validated struct.
6. Response Return: Your controller returns a response struct.
7. Output Transformation: OutTransform is called on the response struct (if implemented).
8. Serialization: Response struct is serialized and sent to the client.