gin

Documentation

Overview

Package gin provides the HTTP bootstrap layer used by GoForge services.

It is responsible for turning the framework configuration into a runnable Gin server with shared middleware, route groups, observability setup, refresh and health handlers, and graceful shutdown coordination.

In a typical application flow this package:

• loads configuration through config/utilities
• initializes logger and OpenTelemetry
• creates the shared gin.Engine
• registers the common middleware stack
• creates the route groups declared in server.groups
• builds the final *http.Server returned by CreateApp

Main entry points:

• CreateApp to initialize configuration and build the HTTP server
• GetEngine to access the shared gin.Engine after CreateApp
• GetRoute to obtain one of the configured route groups
• Start to run the HTTP server and coordinate shutdown

The package also exposes helpers such as SetHostsRefresh and SetFunctionsRefresh, which are used by the built-in refresh propagation flow.

Complete example from a main package:

package main

import (
	"log"

	servergin "github.com/PointerByte/GoForge/config/server/gin"
	"github.com/gin-gonic/gin"
)

func main() {
	srv, err := servergin.CreateApp()
	if err != nil {
		log.Fatal(err)
	}

	api := servergin.GetRoute("/api/v1")
	if api == nil {
		log.Fatal("route group /api/v1 is not configured in server.groups")
	}

	api.GET("/hello", func(c *gin.Context) {
		c.JSON(200, gin.H{
			"message": "ok",
		})
	})

	servergin.Start(srv)
}

In that example, `/api/v1` must exist in the `server.groups` configuration. Once CreateApp succeeds, the package will also register `/health` and `/refresh` under each configured route group.

Index

• func CreateApp() (*http.Server, error)
• func GetEngine() *gin.Engine
• func GetRoute(key string) *gin.RouterGroup
• func SetFunctionsRefresh(input ...HandlerFunctionsRefresh)
• func SetHostsRefresh(input ...string)
• func SetModeTest()
• func SetTLSsConfig(config *tls.Config)
• func Start(srv *http.Server)
• func Stop()
• type HandlerFunctionsRefresh

Functions

func CreateApp

func CreateApp() (*http.Server, error)

CreateApp builds the configured HTTP server for the application.

It loads configuration files and environment overrides, initializes logging and OpenTelemetry, sets up the Gin engine, registers shared middleware, and creates the route groups declared in configuration.

func GetEngine

func GetEngine() *gin.Engine

GetEngine returns the shared Gin engine initialized by CreateApp.

Its main purpose is to expose the configured router after package startup so application code can keep registering routes, groups, middleware, or test requests against the same engine instance that the HTTP server will use.

Typical usage is:

• call CreateApp to load configuration and build the server
• call GetEngine to access the initialized router
• register endpoints directly or through groups returned by GetRoute
• pass the returned server to Start

It returns nil until CreateApp finishes successfully.

func GetRoute

func GetRoute(key string) *gin.RouterGroup

GetRoute returns the Gin route group registered for the provided key.

The key must match one of the configured values from `server.groups`.

func SetFunctionsRefresh

func SetFunctionsRefresh(input ...HandlerFunctionsRefresh)

SetFunctionsRefresh registers refresh callbacks used by the intra-service synchronization flow.

func SetHostsRefresh

func SetHostsRefresh(input ...string)

SetHostsRefresh appends the remote hosts that should receive a refresh notification when this node propagates an update.

func SetModeTest

func SetModeTest()

SetModeTest configures the package for test execution.

It enables logger test mode, switches Gin to test mode, and sets Viper defaults that disable behaviors not needed during tests.

func SetTLSsConfig

func SetTLSsConfig(config *tls.Config)

SetTLSsConfig sets the TLS configuration that CreateApp should attach to the returned http.Server.

It can be used to inject a custom TLS configuration before starting the server. If automatic TLS is also enabled, the auto-generated configuration may replace the previously assigned value.

func Start

func Start(srv *http.Server)

Start runs the provided HTTP server and coordinates the shutdown workflow.

It starts the listener, triggers global jobs startup, logs the configured port, and then executes the registered shutdown handlers before stopping the server.

func Stop

func Stop()

Stop triggers the package shutdown signal used by the graceful-stop flow.

It sends a SIGTERM-like signal through the internal channel after a short delay so the same shutdown path can be used from runtime code and tests.

Types

type HandlerFunctionsRefresh

type HandlerFunctionsRefresh func() error