puff

package module
v0.0.0-...-a782910 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 24, 2024 License: MIT Imports: 26 Imported by: 0

README

Puff

An extensible, performant, and reliable framework inspired by FastAPI.

Features

  • Automatic OpenAPI documentation generation and hosting.
  • Tree-style structure Routers to group APIs.
  • Extensible default middlewares.
  • Customizable logger with structured and prettier logging.
  • Adheres to standards set by net/http, and RFC-compliant.
  • Simplicity where possible and build upon the goated stdlib when possible.
    • Only has 2 external dependencies!

Quickstart

Installation
go get -u github.com/ThePuffProject/puff

Creating a new server using Puff is simple:

import "puff"

app := puff.DefaultApp("Cool Demo App")
app.Use(middleware.Tracing())
app.Use(middleware.Logging())

app.Get("/health", nil, func(c *puff.Context) {
		c.SendResponse(puff.GenericResponse{Content: "Server is Healthy!"})
})

app.ListenAndServe(":8000")

This will begin the application and serve the docs at http://localhost:8000/docs.

The DefaultApp sets up some great defaults, but you can specify a custom config with puff.App().

We also recommend setting up your own logger:

app.Logger = puff.NewLogger(puff.LoggerConfig{
		Level:      slog.LevelDebug,
		Colorize:   true,
		UseJSON:    false,
		TimeFormat: time.DateTime,
})
TODO: improve docs with example on creating a simple router, and contribution docs.

Documentation

Overview

Package logger provides a simple logging implementation to be used in conjunction with Puff.

Package puff provides primitives for implementing a Puff Server

Index

Constants

This section is empty.

Variables

View Source 
var DefaultJSONLoggerConfig = LoggerConfig{
	UseJSON:    true,
	Level:      slog.LevelDebug,
	TimeFormat: time.StampNano,
	Colorize:   false,
}
View Source 
var DefaultLoggerConfig = LoggerConfig{
	UseJSON:    false,
	Level:      slog.LevelInfo,
	TimeFormat: time.UnixDate,
	Colorize:   true,
}
View Source 
var Schemas = make(SchemaDefinition)

Functions

func BadFieldType 

func BadFieldType(k string, got string, expected string) error

func DefaultJSONLogger 

func DefaultJSONLogger() *slog.Logger

DefaultLogger returns a slog.Logger which will use the default json logger.

func DefaultLogger 

func DefaultLogger() *slog.Logger

DefaultLogger returns a slog.Logger which will use the default text logger.

func ExpectedButNotFound 

func ExpectedButNotFound(k string) error

func FieldTypeError 

func FieldTypeError(value string, expectedType string) error

func InvalidJSONError 

func InvalidJSONError(v string) error

func NewLogger 

func NewLogger(c *LoggerConfig) *slog.Logger

NewLogger creates a new *slog.Logger provided the LoggerConfig. Use this function if the default loggers; DefaultLogger and DefaultJSONLogger are not satisfactory.

func RandomNanoID 

func RandomNanoID() string

RandomNanoID generates a random NanoID with format LLLL-NNNN. IMPORTANT: THIS FUNCTION IS NOT CRYPTOGRAPHICALLY SECURE. DO NOT USE THIS TO GENERATE TOKENS WITH AUTHORITY (instead see RandomToken).

func RandomToken 

func RandomToken(length int) string

RandomToken generates a crytographically secure random base64 token with the provided length.

func ResponseType 

func ResponseType[T any]() reflect.Type

func UnexpectedJSONKey 

func UnexpectedJSONKey(k string) error

func Unprocessable 

func Unprocessable(w http.ResponseWriter, r *http.Request)

Types

type AppConfig 

type AppConfig struct {
	// Name is the application name
	Name string
	// Version is the application version.
	Version string
	// DocsURL is the Router prefix for Swagger documentation. Can be "" to disable Swagger documentation.
	DocsURL string
	// TLSPublicCertFile specifies the file for the TLS certificate (usually .pem or .crt).
	TLSPublicCertFile string
	// TLSPrivateKeyFile specifies the file for the TLS private key (usually .key).
	TLSPrivateKeyFile string
	// OpenAPI configuration. Gives users access to the OpenAPI spec generated. Can be manipulated by the user.
	OpenAPI *OpenAPI
	// SwaggerUIConfig is the UI specific configuration.
	SwaggerUIConfig *SwaggerUIConfig
	// LoggerConfig is the application logger config.
	LoggerConfig *LoggerConfig
	// DisableOpenAPIGeneration controls whether an OpenAPI schema will be generated.
	DisableOpenAPIGeneration bool
}

AppConfig defines PuffApp parameters.

type Callback 

type Callback map[string]PathItem

aliases

type Components 

type Components struct {
	Schemas         *SchemaDefinition `json:"schemas,omitempty"`
	Responses       map[string]any    `json:"responses,omitempty"`
	Parameters      map[string]any    `json:"parameters,omitempty"`
	Examples        map[string]any    `json:"examples,omitempty"`
	RequestBodies   map[string]any    `json:"requestBodies,omitempty"`
	Headers         map[string]any    `json:"headers,omitempty"`
	SecuritySchemes map[string]any    `json:"securitySchemes,omitempty"`
	Links           map[string]any    `json:"links,omitempty"`
	Callbacks       map[string]any    `json:"callbacks,omitempty"`
	PathItems       map[string]any    `json:"pathItems,omitempty"`
}

Components struct holds reusable objects for different aspects of the OAS.

func NewComponents 

func NewComponents(a *PuffApp) *Components

type Contact 

type Contact struct {
	Name  string `json:"name,omitempty"`
	URL   string `json:"url,omitempty"`
	Email string `json:"email,omitempty"`
}

Contact struct contains contact information for the API.

type Context 

type Context struct {
	// Request is the underlying *http.Request object.
	Request *http.Request
	// ResponseWriter is the underlying http.ResponseWriter object.
	ResponseWriter http.ResponseWriter

	// WebSocket represents WebSocket connection and its related context, connection, and events.
	// WebSocket will be nil if the route does not use websockets.
	WebSocket *websocket.Conn

	// LoggerConfig
	LoggerConfig LoggerConfig
	// contains filtered or unexported fields
}

Context provides functionality for the route.

func NewContext 

func NewContext(w http.ResponseWriter, r *http.Request, a *PuffApp) *Context

func (*Context) BadRequest 

func (ctx *Context) BadRequest(message string, a ...any)

BadRequest returns a json response with status code 400 a key error and a value of the formatted string from message and the arguments following.

func (*Context) ClientIP 

func (ctx *Context) ClientIP() (IPAddress string)

func (*Context) Forbidden 

func (ctx *Context) Forbidden(message string, a ...any)

Forbidden returns a json response with status code 403 a key error and a value of the formatted string from message and the arguments following.

func (*Context) Get 

func (ctx *Context) Get(key string) any

Get gets a value from Context with the key passed in. It returns nil if the value is not found.

func (*Context) GetBearerToken 

func (ctx *Context) GetBearerToken() string

GetBearerToken gets the Bearer token if it exists. This will work if the request contains an Authorization header that has this syntax: Bearer this_token_here.

func (*Context) GetBody 

func (ctx *Context) GetBody() ([]byte, error)

GetBody returns the request body.

func (*Context) GetCookie 

func (ctx *Context) GetCookie(k string) string

GetCookie retrives a cookie from the context with key "k". If not found, it will return an empty string.

func (*Context) GetFormFile 

func (ctx *Context) GetFormFile(key string) (multipart.File, *multipart.FileHeader, error)

GetFormFile returns the multipart file and the multipart file header associated with the key. It will only provide the first file associated with that form key. It may return an error that is not nil.

func (*Context) GetFormValue 

func (ctx *Context) GetFormValue(k string) string

GetFormValue retrives the value of a form key named k. If not found, it will return an empty string.

func (*Context) GetQueryParam 

func (ctx *Context) GetQueryParam(k string) string

GetQueryParam retrives the value of a query param from k. If not found, it will return an empty string.

func (*Context) GetRequestHeader 

func (ctx *Context) GetRequestHeader(k string) string

GetRequestHeader gets the value of a request header with key k. It returns an empty string if not found.

func (*Context) GetRequestID 

func (ctx *Context) GetRequestID() string

GetRequestID gets the X-Request-ID if set (empty string if not set). puff/middleware provides a tracing middleware the sets X-Request-ID.

func (*Context) GetResponseHeader 

func (ctx *Context) GetResponseHeader(k string) string

GetResponseHeader gets the value of a response header with key k. It returns an empty string if not found.

func (*Context) GetStatusCode 

func (ctx *Context) GetStatusCode() int

GetStatusCode returns the status code. If response not written, returns default 0.

func (*Context) InternalServerError 

func (ctx *Context) InternalServerError(message string, a ...any)

InternalServerError returns a json response with status code 500 with a key error and a value of the formatted string from message and the arguments following.

func (*Context) NotFound 

func (ctx *Context) NotFound(message string, a ...any)

NotFound returns a json response with status code 404 with a key error and a value of the formatted string from message and the arguments following.

func (*Context) SendResponse 

func (c *Context) SendResponse(res Response)

SendResponse sends res back to the client. Any errors at this point will be logged and sending a response will fail.

func (*Context) Set 

func (ctx *Context) Set(key string, value any)

Set sets a value to Context with a key.

func (*Context) SetContentType 

func (ctx *Context) SetContentType(v string)

SetContentType sets the content type of the response.

func (*Context) SetCookie 

func (ctx *Context) SetCookie(cookie *http.Cookie)

SetCookie writes a new cookie to the request with key "k" and value "v". Invalid cookies will be silently dropped. Invalid characters will also be silently dropped. Ex. SetCookie with value ""HELLO WORLD"". The quotation marks are invalid characters, therefore the final cookie will be "HELLO WORLD" instead.

func (*Context) SetResponseHeader 

func (ctx *Context) SetResponseHeader(k, v string)

SetResponseHeader sets the value of the response header k to v.

func (*Context) SetStatusCode 

func (ctx *Context) SetStatusCode(sc int)

SetStatusCode sets the status code of the response.

type Encoding 

type Encoding struct {
	ContentType   string            `json:"contentType,omitempty"`
	Headers       map[string]Header `json:"headers,omitempty"`
	Style         string            `json:"style,omitempty"`
	Explode       bool              `json:"explode,omitempty"`
	AllowReserved bool              `json:"allowReserved,omitempty"`
}

type Example 

type Example struct {
	Summary       string `json:"summary,omitempty"`
	Description   string `json:"description,omitempty"`
	Value         any    `json:"value,omitempty"`
	ExternalValue string `json:"externalValue,omitempty"`
}

type ExternalDocumentation 

type ExternalDocumentation struct {
	Description string `json:"description"`
	URL         string `json:"url"`
}

ExternalDocumentation struct provides external documentation for the API.

type File 

type File struct {
	Name          string
	Size          int64
	MultipartFile multipart.File
}

func (*File) SaveTo 

func (f *File) SaveTo(filepath ...string) (n int, err error)

type FileResponse 

type FileResponse struct {
	StatusCode  int
	FilePath    string
	FileContent []byte
	ContentType string
}

FileResponse represents a response that sends a file.

func (FileResponse) GetContentType 

func (f FileResponse) GetContentType() string

func (FileResponse) GetStatusCode 

func (f FileResponse) GetStatusCode() int

GetStatusCode returns the status code of the file response.

func (*FileResponse) Handler 

func (f *FileResponse) Handler() func(*Context)

Handler returns a handler function for serving the file response.

func (FileResponse) WriteContent 

func (f FileResponse) WriteContent(c *Context) error

WriteContent serves the file from the provided path.

type GenericResponse 

type GenericResponse struct {
	StatusCode  int
	Content     string
	ContentType string
}

GenericResponse represents a response with plain text content.

func (GenericResponse) GetContentType 

func (g GenericResponse) GetContentType() string

func (GenericResponse) GetStatusCode 

func (g GenericResponse) GetStatusCode() int

GetStatusCode returns the status code of the generic response.

func (GenericResponse) WriteContent 

func (g GenericResponse) WriteContent(c *Context) error

GetContent returns the content of the generic response.

type HTMLResponse 

type HTMLResponse struct {
	StatusCode int
	// Content to render if TemplateFile is not used.
	Content string
	// TemplateFile is the path to the template file to use.
	TemplateFile string
	// Template is the inline template string. (optional)
	Template string
	// Data to pass to the template.
	Data any
}

HTMLResponse represents a response with HTML content. It supports both file-based templates and inline string templates.

func (HTMLResponse) GetContentType 

func (h HTMLResponse) GetContentType() string

func (HTMLResponse) GetStatusCode 

func (h HTMLResponse) GetStatusCode() int

GetStatusCode returns the status code of the HTML response.

func (HTMLResponse) WriteContent 

func (h HTMLResponse) WriteContent(c *Context) error

WriteContent writes the HTML content to the response. It checks whether to use an inline template or a template file.

type HandlerFunc 

type HandlerFunc func(*Context)
type Header struct {
}

type Info 

type Info struct {
	Title   string `json:"title"`
	Summary string `json:"summary"`
	// Description is an html string that describes the API service. Do *NOT* include <Doctype> or <html> tags.
	Description    string   `json:"description"`
	TermsOfService string   `json:"termsOfService"`
	Contact        *Contact `json:"contact"`
	License        *License `json:"license"`
	Version        string   `json:"version"`
}

Info struct provides metadata about the API.

type JSONResponse 

type JSONResponse struct {
	StatusCode int
	Content    any
}

JSONResponse represents a response with JSON content.

func (JSONResponse) GetContentType 

func (j JSONResponse) GetContentType() string

func (JSONResponse) GetStatusCode 

func (j JSONResponse) GetStatusCode() int

GetStatusCode returns the status code of the JSON response.

func (JSONResponse) WriteContent 

func (j JSONResponse) WriteContent(c *Context) error

GetContent returns the content of the JSON response.

type License 

type License struct {
	Name       string `json:"name"`
	Identifier string `json:"identifier,omitempty"`
	Url        string `json:"url,omitempty"`
}

License struct contains license information for the API. 

type Link struct {
	OperationRef string `json:"operationRef,omitempty"`
	OperationID  string `json:"operationId,omitempty"`
	Parameters   any    `json:"parameters,omitempty"`
	RequestBody  any    `json:"requestBody,omitempty"`
	Description  string `json:"description,omitempty"`
	Server       Server `json:"server,omitempty"`
}

type LoggerConfig 

type LoggerConfig struct {
	// UseJSON will enable/disable JSON mode for the logger.
	UseJSON bool
	// Indent will control whether to use MarshalIndent or Marshal for logging.
	Indent bool
	// Level is the logger level. Logger will only write to stdout if log record is above or equivalent to Level.
	Level slog.Level
	// TimeFormat is the textual representation of the timestamp. It is passed as an argument to time.Format()
	TimeFormat string
	// AddSource is equivalent to slog.HandlerOptions.AddSource
	AddSource bool
	// Colorize enables or disables pretty logging dependant on LogLevel.
	Colorize bool
}

LoggerConfig is used to dictate logger behavior.

type MediaType 

type MediaType struct {
	Schema   *Schema        `json:"schema"`
	Example  any            `json:"example,omitempty"`
	Examples map[string]any `json:"examples,omitempty"`
}

MediaType struct describes a media type object in OpenAPI.

type Middleware 

type Middleware func(next HandlerFunc) HandlerFunc

type OpenAPI 

type OpenAPI struct {
	SpecVersion       string                 `json:"openapi"`
	Info              *Info                  `json:"info"`
	JSONSchemaDialect string                 `json:"jsonSchemaDialect"`
	Servers           *[]Server              `json:"servers"`
	Paths             *Paths                 `json:"paths"`
	Webhooks          map[string]any         `json:"webhooks"`
	Components        *Components            `json:"components"`
	Security          *[]SecurityRequirement `json:"security"`
	Tags              *[]Tag                 `json:"tags"`
	ExternalDocs      *ExternalDocumentation `json:"externalDocs"`
	// contains filtered or unexported fields
}

OpenAPI struct represents the root of the OpenAPI document.

func NewOpenAPI 

func NewOpenAPI(a *PuffApp) *OpenAPI

type OpenAPIResponse 

type OpenAPIResponse struct {
	Description string               `json:"description"`
	Headers     map[string]Header    `json:"headers,omitempty"`
	Content     map[string]MediaType `json:"content,omitempty"`
	Links       map[string]Link      `json:"links,omitempty"`
}

OpenAPIResponse struct describes possible responses in OpenAPI.

type Operation 

type Operation struct {
	Tags         []string                   `json:"tags"`
	Summary      string                     `json:"summary"`
	Description  string                     `json:"description"`
	ExternalDocs ExternalDocumentation      `json:"externalDocs"`
	OperationID  string                     `json:"operationId"`
	Parameters   []Parameter                `json:"parameters"`
	RequestBody  *RequestBodyOrReference    `json:"requestBody,omitempty"`
	Responses    map[string]OpenAPIResponse `json:"responses"`
	Callbacks    map[string]Callback        `json:"callbacks"`
	Deprecated   bool                       `json:"deprecated"`
	Security     *[]SecurityRequirement     `json:"security,omitempty"`
	Servers      *[]Server                  `json:"servers,omitempty"`
}

Operation struct describes an operation in a PathItem.

type Parameter 

type Parameter struct {
	Name            string  `json:"name"`
	In              string  `json:"in"`
	Description     string  `json:"description"`
	Required        bool    `json:"required"`
	Type            string  `json:"type"`
	Deprecated      bool    `json:"deprecated"`
	AllowEmptyValue bool    `json:"allowEmptyValue"`
	Style           string  `json:"style"`
	Explode         bool    `json:"explode"`
	AllowReserved   bool    `json:"allowReserved"`
	Schema          *Schema `json:"schema"`
}

Parameter struct describes a parameter in OpenAPI.

type PathItem 

type PathItem struct {
	Ref         string       `json:"$ref"`
	Summary     string       `json:"summary"`
	Description string       `json:"description"`
	Get         *Operation   `json:"get,omitempty"`
	Put         *Operation   `json:"put,omitempty"`
	Post        *Operation   `json:"post,omitempty"`
	Delete      *Operation   `json:"delete,omitempty"`
	Options     *Operation   `json:"options,omitempty"`
	Head        *Operation   `json:"head,omitempty"`
	Patch       *Operation   `json:"patch,omitempty"`
	Trace       *Operation   `json:"trace,omitempty"`
	Servers     *[]Server    `json:"servers,omitempty"`
	Parameters  *[]Parameter `json:"parameters,omitempty"`
}

PathItem struct describes operations available on a single path.

type Paths 

type Paths map[string]PathItem

type Property 

type Property struct {
	Type    string `json:"type"`
	Format  string `json:"format"`
	Example any    `json:"example"`
}

Property defines a property in the OpenAPI spec that defines information about a property (parameters, definitions, etc).

type PuffApp 

type PuffApp struct {
	// Config is the underlying application configuration.
	Config *AppConfig
	// RootRouter is the application's default router.
	RootRouter *Router

	// Server is the http.Server that will be used to serve requests.
	Server *http.Server
}

func App 

func App(c *AppConfig) *PuffApp

func DefaultApp 

func DefaultApp(name string) *PuffApp

func (*PuffApp) AllRoutes 

func (a *PuffApp) AllRoutes() []*Route

AllRoutes returns all routes registered in the PuffApp, including those in sub-routers. This function provides an aggregated view of all routes in the application.

func (*PuffApp) Close 

func (a *PuffApp) Close() error

Close calls close on the underlying server.

func (*PuffApp) Delete 

func (a *PuffApp) Delete(path string, fields any, handleFunc func(*Context)) *Route

Delete registers an HTTP DELETE route in the PuffApp's root router.

Parameters: - path: The URL path of the route. - fields: Optional fields associated with the route. - handleFunc: The handler function that will be executed when the route is accessed.

func (*PuffApp) GenerateDefinitions 

func (a *PuffApp) GenerateDefinitions(paths Paths) map[string]*Schema

GenerateDefinitions is a helper function that takes a list of Paths and generates the OpenAPI schema for each path.

func (*PuffApp) GenerateOpenAPISpec 

func (a *PuffApp) GenerateOpenAPISpec()

GenerateOpenAPISpec is responsible for taking the PuffApp configuration and turning it into an OpenAPI json.

func (*PuffApp) GeneratePathsTags 

func (a *PuffApp) GeneratePathsTags() (*Paths, *[]Tag)

GeneratePathsTags is a helper function to auto-define OpenAPI tags and paths if you would like to customize OpenAPI schema. Returns (paths, tags) to populate the 'Paths' and 'Tags' attribute of OpenAPI

func (*PuffApp) Get 

func (a *PuffApp) Get(path string, fields any, handleFunc func(*Context)) *Route

Get registers an HTTP GET route in the PuffApp's root router.

Parameters: - path: The URL path of the route. - fields: Optional fields associated with the route. - handleFunc: The handler function that will be executed when the route is accessed.

func (*PuffApp) IncludeRouter 

func (a *PuffApp) IncludeRouter(r *Router)

Add a Router to the main app. Under the hood attaches the router to the App's RootRouter

func (*PuffApp) ListenAndServe 

func (a *PuffApp) ListenAndServe(listenAddr string) error

ListenAndServe starts the PuffApp server on the specified address. Before starting, it patches all routes, adds OpenAPI documentation routes (if available), and sets up logging.

If TLS certificates are provided (TLSPublicCertFile and TLSPrivateKeyFile), the server starts with TLS enabled; otherwise, it runs a standard HTTP server.

Parameters: - listenAddr: The address the server will listen on (e.g., ":8080").

func (*PuffApp) Patch 

func (a *PuffApp) Patch(path string, fields any, handleFunc func(*Context)) *Route

Patch registers an HTTP PATCH route in the PuffApp's root router.

Parameters: - path: The URL path of the route. - fields: Optional fields associated with the route. - handleFunc: The handler function that will be executed when the route is accessed.

func (*PuffApp) Post 

func (a *PuffApp) Post(path string, fields any, handleFunc func(*Context)) *Route

Post registers an HTTP POST route in the PuffApp's root router.

Parameters: - path: The URL path of the route. - fields: Optional fields associated with the route. - handleFunc: The handler function that will be executed when the route is accessed.

func (*PuffApp) Put 

func (a *PuffApp) Put(path string, fields any, handleFunc func(*Context)) *Route

Put registers an HTTP PUT route in the PuffApp's root router.

Parameters: - path: The URL path of the route. - fields: Optional fields associated with the route. - handleFunc: The handler function that will be executed when the route is accessed.

func (*PuffApp) Shutdown 

func (a *PuffApp) Shutdown(ctx context.Context) error

Shutdown calls shutdown on the underlying server with a non-nil empty context.

func (*PuffApp) Use 

func (a *PuffApp) Use(m Middleware)

Use registers a middleware function to be used by the root router of the PuffApp. The middleware will be appended to the list of middlewares in the root router.

Parameters: - m: Middleware function to be added.

func (*PuffApp) WebSocket 

func (a *PuffApp) WebSocket(path string, fields any, handleFunc func(*Context)) *Route

WebSocket registers a WebSocket route in the PuffApp's root router. This route allows the server to handle WebSocket connections at the specified path.

Parameters: - path: The URL path of the WebSocket route. - fields: Optional fields associated with the route. - handleFunc: The handler function to handle WebSocket connections.

type RedirectResponse 

type RedirectResponse struct {
	// StatusCode provides the 3xx status code of the redirect response. Default: 308.
	StatusCode int
	// To provides the URL to redirect the client to.
	To string
}

RedirectResponse represents a response that sends a redirect to the client.

func (RedirectResponse) GetContentType 

func (r RedirectResponse) GetContentType() string

GetContentType returns the content type for the redirect response. It will always return an empty string since there is no body to describe in content typc.ResponseWriter.

func (RedirectResponse) GetStatusCode 

func (r RedirectResponse) GetStatusCode() int

GetStatusCode returns the status code for the redirect response. If the status code is not provided, or not valid for a redirect, it will default to 308.

func (RedirectResponse) WriteContent 

func (r RedirectResponse) WriteContent(c *Context) error

WriteContent writes the header Location to redirect the client to.

type Reference 

type Reference struct {
	Ref         string `json:"$ref"`
	Summary     string `json:"$summary"`
	Description string `json:"$description"`
}

type RequestBodyOrReference 

type RequestBodyOrReference struct {
	Reference   string               `json:"$ref,omitempty"`
	Description string               `json:"description,omitempty"`
	Content     map[string]MediaType `json:"content,omitempty"`
	Required    bool                 `json:"required,omitempty"`
}

RequestBodyOrReference is a union type representing either a Request Body Object or a Reference Object.

type Response 

type Response interface {
	GetStatusCode() int
	GetContentType() string
	WriteContent(*Context) error
}

Response is an interface that all response types should implement.

type ResponseDefinition 

type ResponseDefinition struct {
	StatusCode   int
	ResponseType func() reflect.Type
}

ResponseDefinition represents a definition of a response for a specific HTTP status code. It is used to map an HTTP status code to the corresponding response type for a route. Puff uses this to automatically generate Swagger documentation.

Fields:

  • StatusCode: The HTTP status code associated with this response (e.g., http.StatusOK for success,http.StatusNotFound for not found).
  • ResponseType: The Go type that defines the response body (e.g., a struct). This type is used to generate the corresponding Swagger schema. The type should not be an instance; just the a function returning reflect.Type (e.g., `puff.ResponseType[Pizza]`).

func DefineResponse 

func DefineResponse(statusCode int, ResponseType func() reflect.Type) ResponseDefinition

DefineResponse creates a ResponseDefinition mapping an HTTP status code to the corresponding response type for a route.

Example: 

app.Get("/pizza", handler).WithResponses(
    puff.DefineResponse(http.StatusOK, PizzaResponse),
    puff.DefineResponse(http.StatusNotFound, ErrorResponse),
)

Parameters:

  • statusCode: The HTTP status code that this response corresponds to.
  • ResponseType: The Go type that represents the response body. This should be the type (not an instance) of the struct that defines the response schema.

Returns: - A ResponseDefinition that maps the provided status code to the response type.

type Responses 

type Responses = map[int]func() reflect.Type

Responses type maps together the HTTPStatusCode with a function returning the reflect.Type

type Route 

type Route struct {
	Description string
	WebSocket   bool
	Protocol    string
	Path        string
	Handler     func(*Context)
	Fields      any
	// Router points to the router the route belongs to. Will always be the closest router in the tree.
	Router *Router
	// Responses are the schemas associated with a specific route. Have preference over parent router defined routes.
	// Preferably set Responses using the WithResponse/WithResponses method on Route.
	Responses Responses
	// contains filtered or unexported fields
}

func (*Route) GenerateResponses 

func (r *Route) GenerateResponses()

GenerateResponses is responsible for generating the 'responses' attribute in the OpenAPI schema. Since responses can be specified at multiple levels, responses at the route level will be given the most specificity.

func (*Route) GetFullPath 

func (r *Route) GetFullPath() string

func (*Route) String 

func (r *Route) String() string

func (*Route) WithResponse 

func (r *Route) WithResponse(statusCode int, ResponseTypeFunc func() reflect.Type) *Route

WithResponse registers a single response type for a specific HTTP status code for the route. This method is used exclusively for generating Swagger documentation, allowing users to specify the response type that will be represented in the Swagger API documentation when this status code is encountered.

Example usage: 

app.Get("/pizza", func(c puff.Context) {
    c.SendResponse(puff.JSONResponse{http.StatusOK, PizzaResponse{Name: "Margherita", Price: 10, Size: "Medium"}})
}).WithResponse(http.StatusOK, puff.ResponseType[PizzaResponse])

Parameters:

  • statusCode: The HTTP status code that this response corresponds to.
  • ResponseType: The Go type that represents the structure of the response body. This should be the type (not an instance) of the struct that defines the response schema.

Returns: - The updated Route object to allow method chaining.

func (*Route) WithResponses 

func (r *Route) WithResponses(responses ...ResponseDefinition) *Route

WithResponses registers multiple response types for different HTTP status codes for the route. This method is used exclusively for generating Swagger documentation, allowing users to define various response types based on the possible outcomes of the route's execution, as represented in the Swagger API documentation.

Example usage: 

app.Get("/pizza", func(c puff.Context) {
    ~ logic here
    if found {
        c.SendResponse(puff.JSONResponse{http.StatusOK, PizzaResponse{Name: "Margherita", Price: 10, Size: "Medium"}})
    } else {
        c.SendResponse(puff.JSONResponse{http.StatusNotFound, ErrorResponse{Message: "Not Found"}})
    }
}).WithResponses(
    puff.DefineResponse(http.StatusOK, puff.ResponseType[PizzaResponse]),
    puff.DefineResponse(http.StatusNotFound, puff.ResponseType[ErrorResponse]),
)

Parameters:

  • responses: A variadic list of ResponseDefinition objects that define the mapping between HTTP status codes and their corresponding response types. Each ResponseDefinition includes a status code and a type representing the response body structure.

Returns: - The updated Route object to allow method chaining.

type Router 

type Router struct {
	Name        string
	Prefix      string //(optional) prefix, all Routes underneath will have paths that start with the prefix automatically
	Routers     []*Router
	Routes      []*Route
	Middlewares []*Middleware
	Tag         string
	Description string
	// Responses is a map of status code to puff.Response. Possible Responses for routes can be set at the Router (root as well),
	// and Route level, however responses directly set on the route will have the highest specificity.
	Responses Responses
	// contains filtered or unexported fields
}

Router defines a group of routes that share the same prefix and middlewares.

func NewRouter 

func NewRouter(name string, prefix string) *Router

NewRouter creates a new router provided router name and path prefix.

func (*Router) AllRoutes 

func (r *Router) AllRoutes() []*Route

AllRoutes returns all routes attached to a router as well as routes attached to the subrouters For just the routes attached to a router, use `Routes` attribute on Router

func (*Router) Delete 

func (r *Router) Delete(
	path string,
	fields any,
	handleFunc func(*Context),
) *Route

func (*Router) Get 

func (r *Router) Get(
	path string,
	fields any,
	handleFunc func(*Context),
) *Route

func (*Router) IncludeRouter 

func (r *Router) IncludeRouter(rt *Router)

func (*Router) Patch 

func (r *Router) Patch(
	path string,
	fields any,
	handleFunc func(*Context),
) *Route

func (*Router) Post 

func (r *Router) Post(
	path string,
	fields any,
	handleFunc func(*Context),
) *Route

func (*Router) Put 

func (r *Router) Put(
	path string,
	fields any,
	handleFunc func(*Context),
) *Route

func (*Router) ServeHTTP 

func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request)

func (*Router) String 

func (r *Router) String() string

func (*Router) Use 

func (r *Router) Use(m Middleware)

Use adds a middleware to the router's list of middlewares. Middleware functions can be used to intercept requests and responses, allowing for functionality such as logging, authentication, and error handling to be applied to all routes managed by this router.

Example usage: 

router := puff.NewRouter()
router.Use(myMiddleware)
router.Get("/endpoint", myHandler)

Parameters: - m: A Middleware function that will be applied to all routes in this router. TODO: dont know if below is actually accurate. cant think Note: Middleware functions are executed in the order they are added. If multiple middlewares are registered, they will be executed sequentially for each request handled by the router.

func (*Router) WebSocket 

func (r *Router) WebSocket(
	path string,
	fields any,
	handleFunc func(*Context),
) *Route

type Schema 

type Schema struct {
	// Define your schema fields based on your specific requirements
	// Example fields could include type, format, properties, etc.
	// This can be expanded based on the needs of your application.
	Type                 string             `json:"type,omitempty"`
	Format               string             `json:"format,omitempty"`
	Minimum              string             `json:"minimum,omitempty"`
	Items                *Schema            `json:"items,omitempty"`
	Ref                  string             `json:"$ref,omitempty"`
	Properties           map[string]*Schema `json:"properties,omitempty"`
	AdditionalProperties *Schema            `json:"additionalProperties,omitempty"`
	Required             []string           `json:"required,omitempty"`
	Examples             []any              `json:"examples,omitempty"`
}

Schema struct represents a schema object in OpenAPI.

type SchemaDefinition 

type SchemaDefinition map[string]*Schema

type SecurityRequirement 

type SecurityRequirement map[string][]string

type Server 

type Server struct {
	URL         string                    `json:"url"`
	Description string                    `json:"description"`
	Variables   map[string]ServerVariable `json:"variables"`
}

Server struct represents a server object in OpenAPI.

type ServerSideEvent 

type ServerSideEvent struct {
	Event string
	Data  string
	ID    string
	Retry int
}

type ServerVariable 

type ServerVariable struct {
	Enum        []string `json:"enum,omitempty"`
	Default     string   `json:"default"`
	Description string   `json:"description,omitempty"`
}

type SlogHandler 

type SlogHandler struct {
	slog.Handler
	// contains filtered or unexported fields
}

SlogHandler is puff's implementation of structured logging. It wraps golang's slog package.

func NewSlogHandler 

func NewSlogHandler(config LoggerConfig) *SlogHandler

NewSlogHandler returns a new puff.SlogHandler given a LoggerConfig and slog.Handler

func (*SlogHandler) Enabled 

func (h *SlogHandler) Enabled(c context.Context, level slog.Level) bool

Enabled will check if a log needs to be written to stdout.

func (*SlogHandler) Handle 

func (h *SlogHandler) Handle(c context.Context, r slog.Record) error

Handle will write to stdout.

func (*SlogHandler) SetLevel 

func (h *SlogHandler) SetLevel(level slog.Level)

SetLevel changes the puff.SlogHandler level to the one specified.

type StreamingResponse 

type StreamingResponse struct {
	StatusCode int
	// StreamHandler is a function that takes in a pointer to a channel.
	// The channel should be written to with a ServerSideEvent to write
	// to the response. It should be closed once done writing.
	StreamHandler func(*chan ServerSideEvent)
}

StreamingResponse represents a response that streams content.

func (StreamingResponse) GetContentType 

func (s StreamingResponse) GetContentType() string

func (StreamingResponse) GetStatusCode 

func (s StreamingResponse) GetStatusCode() int

GetStatusCode returns the status code of the streaming response.

func (StreamingResponse) Handler 

func (s StreamingResponse) Handler() func(*Context)

func (StreamingResponse) WriteContent 

func (s StreamingResponse) WriteContent(c *Context) error

GetContent returns the content of the streaming response.

type SwaggerUIConfig 

type SwaggerUIConfig struct {
	// Title of the Swagger Page
	Title string
	// URL of OpenAPI JSON
	URL string
	// One of the 7 themes supported by Swagger, e.g 'nord'.
	Theme string
	// Filter controls whether to display a tag-based filter on the OpenAPI UI
	Filter bool
	// RequestDuration controls whether to display the request duration after firing a request.
	RequestDuration bool
	// FaviconURL is the location of favicon image to display
	FaviconURL string
}

SwaggerUIConfig is the subset of the SwaggerUI configurables that Puff supports. To learn more, please read [SwaggerDocs](https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/).

type Tag 

type Tag struct {
	Name         string                `json:"name"`
	Description  string                `json:"description"`
	ExternalDocs ExternalDocumentation `json:"externalDocs,omitempty"`
}

Tag struct represents a tag used by the OpenAPI document.

Source Files

View all Source files

Directories

Path Synopsis
Package middleware provides middlewares for handling common web application requirements.
 Package middleware provides middlewares for handling common web application requirements.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.