solanum

README

Solanum - Web Server Framework Based on Gin

Solanum is a lightweight, Gin-based web framework for Go that brings a clean modular structure and built-in dependency injection (DI). It makes it easy to organize your routes, middleware, and service dependencies in a scalable, testable way.

Annuums, Potato Can Change The World!

• Eugene
  • Github

Features

• Modular Architecture
  Define self-contained Modules, each with its own URI prefix, middleware, controllers, and dependencies.

• Controller & Service Layer
  Organize handlers as SolaService entries within Controllers, enabling clear separation of concerns.

• Dependency Injection Container
  Register providers (factory functions or concrete instances) with singleton or transient scope, support init hooks, and resolve by key or Go interface type.

• Flexible CORS Support
  Fluent API for configuring origins, methods, headers, credentials, and max age.

Installation

go get github.com/annuums/solanum

Quick Start

package main

import "github.com/annuums/solanum"

func main() {
	server := *solanum.NewSolanum(5050)

	healthCheckUri := "/ping"
	healthCheckModule := solanum.NewHealthCheckModule(
		healthCheckUri,
	)

	server.SetModules(healthCheckModule)

	server.Run()
}

👉 Examples

Documentation

Index

• type Controller
• type Module
• type Runner
  • func NewSolanum(port int) *Runner
• type SolaController
  • func NewController() *SolaController
  • func (ctr *SolaController) Handlers() []*SolaService
  • func (ctr *SolaController) SetHandlers(handlers ...*SolaService)
• type SolaModule
  • func NewModule(uri string) *SolaModule
  • func (m *SolaModule) AddPostMiddleware(middleware gin.HandlerFunc)
  • func (m *SolaModule) AddPreMiddleware(middleware gin.HandlerFunc)
  • func (m *SolaModule) Controllers() []Controller
  • func (m *SolaModule) Dependencies() *[]*container.DependencyConfig
  • func (m *SolaModule) PostMiddlewares() []gin.HandlerFunc
  • func (m *SolaModule) PreMiddlewares() []gin.HandlerFunc
  • func (m *SolaModule) SetControllers(c ...Controller)
  • func (m *SolaModule) SetDependencies(deps ...container.DependencyConfig)
  • func (m *SolaModule) SetPostMiddlewares(middlewares ...gin.HandlerFunc)
  • func (m *SolaModule) SetPreMiddlewares(middlewares ...gin.HandlerFunc)
  • func (m *SolaModule) SetRoutes(router *gin.RouterGroup)
  • func (m *SolaModule) Uri() string
• type SolaService

Types

type Controller

type Controller interface {
	// Handlers returns the slice of service definitions this controller manages.
	Handlers() []*SolaService

	// SetHandlers adds one or more SolaService entries to the controller.
	SetHandlers(handler ...*SolaService)
}

Controller declares a set of service handlers for a logical grouping of routes.

type Module

type Module interface {
	// PreMiddlewares returns middleware to run before each handler.
	PreMiddlewares() []gin.HandlerFunc

	// AddPreMiddleware appends a middleware to the pre-handler chain.
	AddPreMiddleware(middleware gin.HandlerFunc)

	// SetPreMiddlewares replaces the entire pre-handler middleware chain.
	SetPreMiddlewares(middlewares ...gin.HandlerFunc)

	// PostMiddlewares returns middleware to run after each handler.
	PostMiddlewares() []gin.HandlerFunc

	// AddPostMiddleware appends a middleware to the post-handler chain.
	AddPostMiddleware(middleware gin.HandlerFunc)

	// SetPostMiddlewares replaces the entire post-handler middleware chain.
	SetPostMiddlewares(middlewares ...gin.HandlerFunc)

	// Controllers returns the slice of Controller implementations in this module.
	Controllers() []Controller

	// SetControllers registers one or more Controller implementations.
	SetControllers(c ...Controller)

	// Dependencies returns the list of dependencies that this module injects.
	Dependencies() *[]*container.DependencyConfig

	// SetDependencies defines which dependencies to inject via middleware.
	SetDependencies(deps ...container.DependencyConfig)

	// SetRoutes binds the module's controllers, middleware, and routes onto a RouterGroup.
	SetRoutes(router *gin.RouterGroup)

	// Uri returns the base URI path for this module (e.g., "/users").
	Uri() string
}

Module represents a self-contained HTTP module with its own URI prefix, middleware layers, controllers, and dependencies.

type Runner

type Runner interface {
	// InitModules sets up all registered modules and their routes.
	InitModules()

	// InitGlobalMiddlewares registers any application-wide middleware.
	InitGlobalMiddlewares()

	// Modules returns a slice of pointers to registered Modules.
	Modules() []*Module

	// SetModules registers one or more Modules with the Runner.
	SetModules(m ...Module)

	// GinEngine exposes the underlying *gin.Engine for custom setup.
	GinEngine() *gin.Engine

	// Cors applies CORS configuration to the Gin engine using functional options.
	Cors(opts ...func(*util.CorsOption))

	// ValidateDependencies checks that all dependencies are registered.
	ValidateDependencies() error

	// Run boots the HTTP server, initializing modules and listening on the configured port.
	Run()
}

Runner is the application entrypoint interface for Solanum. It manages module initialization, global middlewares, CORS, and server start.

var SolanumRunner Runner

SolanumRunner holds the global Runner instance used to configure and start the server.

func NewSolanum

func NewSolanum(port int) *Runner

NewSolanum creates (once) and returns the global Runner configured for the given port. It ensures global middlewares are initialized. Subsequent calls return the same Runner.

type SolaController

type SolaController struct {
	// contains filtered or unexported fields
}

SolaController groups one or more SolaService handlers under a logical controller. It implements the Controller interface, managing a list of SolaService entries.

func NewController

func NewController() *SolaController

NewController constructs an empty SolaController ready to receive handlers.

func (*SolaController) Handlers

func (ctr *SolaController) Handlers() []*SolaService

Handlers returns the slice of SolaService entries managed by this controller.

func (*SolaController) SetHandlers

func (ctr *SolaController) SetHandlers(handlers ...*SolaService)

SetHandlers appends one or more SolaService entries to the controller's handler list.

type SolaModule

type SolaModule struct {
	// contains filtered or unexported fields
}

SolaModule encapsulates a self-contained HTTP module with its own URI prefix, controllers, middleware stacks, and dependency configurations.

func NewModule

func NewModule(uri string) *SolaModule

NewModule creates a new SolaModule with the given URI prefix. The module starts with empty controller, middleware, and dependency lists.

func (*SolaModule) AddPostMiddleware

func (m *SolaModule) AddPostMiddleware(middleware gin.HandlerFunc)

AddPostMiddleware appends a single middleware to the post-handler chain.

func (*SolaModule) AddPreMiddleware

func (m *SolaModule) AddPreMiddleware(middleware gin.HandlerFunc)

AddPreMiddleware appends a single middleware to the pre-handler chain.

func (*SolaModule) Controllers

func (m *SolaModule) Controllers() []Controller

Controllers returns all controllers registered in this module.

func (*SolaModule) Dependencies

func (m *SolaModule) Dependencies() *[]*container.DependencyConfig

Dependencies returns the list of DependencyConfig entries for this module.

func (*SolaModule) PostMiddlewares

func (m *SolaModule) PostMiddlewares() []gin.HandlerFunc

PostMiddlewares returns the list of middleware to execute after handlers.

func (*SolaModule) PreMiddlewares

func (m *SolaModule) PreMiddlewares() []gin.HandlerFunc

PreMiddlewares returns the list of middleware to execute before handlers.

func (*SolaModule) SetControllers

func (m *SolaModule) SetControllers(c ...Controller)

SetControllers registers one or more Controller implementations for this module.

func (*SolaModule) SetDependencies

func (m *SolaModule) SetDependencies(deps ...container.DependencyConfig)

SetDependencies replaces the module's dependency list with the provided configs.

func (*SolaModule) SetPostMiddlewares

func (m *SolaModule) SetPostMiddlewares(middlewares ...gin.HandlerFunc)

SetPostMiddlewares replaces the post-handler middleware chain with the provided list.

func (*SolaModule) SetPreMiddlewares

func (m *SolaModule) SetPreMiddlewares(middlewares ...gin.HandlerFunc)

SetPreMiddlewares replaces the pre-handler middleware chain with the provided list.

func (*SolaModule) SetRoutes

func (m *SolaModule) SetRoutes(router *gin.RouterGroup)

SetRoutes registers the module's routes, middleware, and DI middleware on the given RouterGroup. It applies DI if dependencies are defined, then mounts each SolaService handler with pre- and post-middleware.

func (*SolaModule) Uri

func (m *SolaModule) Uri() string

Uri returns the base URI prefix for this module.

type SolaService

type SolaService struct {
	// Uri the relative path for the service (e.g., "/:id")
	// route URI relative to module prefix
	Uri string

	// Method the HTTP method to bind (GET, POST, etc.)
	Method string

	// Handler the Gin handler function to execute
	Handler gin.HandlerFunc
}

SolaService represents a single HTTP route handler configuration.