ginmiddleware

README

gin

gin provides middleware for easy tenant context management in web applications. It integrates seamlessly with the gorm-multitenancy package.

Installation

go get -u github.com/bartventer/gorm-multitenancy/middleware/gin/v8

Getting Started

Check out the pkg.go.dev documentation for comprehensive guides and API references.

Running the Example Application

For a practical demonstration, you can run the example application. It showcases various configurations and usage scenarios.

Contributing

All contributions are welcome! See the Contributing Guide for more details.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Documentation

Overview

Package ginmiddleware provides a middleware for the Gin framework, which adds multi-tenancy support.

Example usage:

import (
    "net/http"

    ginmiddleware "github.com/bartventer/gorm-multitenancy/middleware/gin/v8"
    "github.com/bartventer/gorm-multitenancy/v8"
    "github.com/gin-gonic/gin"
)

func main() {
    r := gin.Default()

    r.Use(ginmiddleware.WithTenant(ginmiddleware.DefaultWithTenantConfig))

    r.GET("/", func(c *gin.Context) {
        tenant := c.GetString(ginmiddleware.TenantKey)
        c.String(http.StatusOK, "Hello, "+tenant)
    })

    r.Run(":8080")
}

Index

• Constants
• Variables
• func DefaultSkipper(c *gin.Context) bool
• func DefaultTenantFromHeader(c *gin.Context) (string, error)
• func DefaultTenantFromSubdomain(c *gin.Context) (string, error)
• func WithTenant(config WithTenantConfig) gin.HandlerFunc
• type WithTenantConfig

Examples

• WithTenant

Constants

const XTenantHeader = nethttp.XTenantHeader

XTenantHeader is an alias for nethttp.XTenantHeader.

Variables

var (
	// DefaultWithTenantConfig is the default configuration for the WithTenant middleware.
	DefaultWithTenantConfig = WithTenantConfig{
		Skipper: DefaultSkipper,
		TenantGetters: []func(c *gin.Context) (string, error){
			DefaultTenantFromSubdomain,
			DefaultTenantFromHeader,
		},
		ContextKey: TenantKey,
		ErrorHandler: func(c *gin.Context, _ error) {
			c.AbortWithStatusJSON(http.StatusInternalServerError, gin.H{"error": nethttpmw.ErrTenantInvalid.Error()})
		},
	}
)

var ErrTenantInvalid = nethttp.ErrTenantInvalid

ErrTenantInvalid is an alias for nethttp.ErrTenantInvalid.

var ExtractSubdomain = nethttpmw.ExtractSubdomain

ExtractSubdomain is an alias for nethttpmw.ExtractSubdomain.

var (
	// TenantKey is the key that holds the tenant in a request context.
	TenantKey = &contextKey{"tenant"}
)

Functions

func DefaultSkipper

func DefaultSkipper(c *gin.Context) bool

DefaultSkipper returns false which processes the middleware.

func DefaultTenantFromHeader

func DefaultTenantFromHeader(c *gin.Context) (string, error)

DefaultTenantFromHeader extracts the tenant from the header in the HTTP request.

func DefaultTenantFromSubdomain

func DefaultTenantFromSubdomain(c *gin.Context) (string, error)

DefaultTenantFromSubdomain extracts the subdomain from the given HTTP request's host.

func WithTenant

func WithTenant(config WithTenantConfig) gin.HandlerFunc

WithTenant is a middleware function that adds multi-tenancy support to a Gin application.

Example

r := gin.Default()

r.Use(WithTenant(DefaultWithTenantConfig))

r.GET("/", func(c *gin.Context) {
	tenant := c.GetString(TenantKey.String())
	fmt.Println("Tenant:", tenant)
	c.String(http.StatusOK, "Hello, "+tenant)
})

req := httptest.NewRequest(http.MethodGet, "/", nil)
req.Host = "tenant.example.com"
w := httptest.NewRecorder()

// Execute the request
r.ServeHTTP(w, req)

Output:

Tenant: tenant

Types

type WithTenantConfig

type WithTenantConfig struct {

	// Skipper defines a function to skip the middleware.
	Skipper func(c *gin.Context) bool

	// TenantGetters is a list of functions that retrieve the tenant from the request.
	// Each function should return the tenant as a string and an error if any.
	// The functions are executed in order until a valid tenant is found.
	TenantGetters []func(c *gin.Context) (string, error)

	// ContextKey is the key used to store the tenant in the context.
	ContextKey fmt.Stringer

	// ErrorHandler is a callback function that is called when an error occurs during the tenant retrieval process.
	ErrorHandler func(c *gin.Context, err error)

	// SuccessHandler is a callback function that is called after the tenant is successfully set in the Gin context.
	// It can be used to perform additional operations, such as modifying the database connection based on the tenant.
	SuccessHandler func(c *gin.Context)
}

WithTenantConfig represents the configuration options for the tenant middleware in Gin.