react

README

 ███████████   ██████████   █████████     █████████  ███████████
░░███░░░░░███ ░░███░░░░░█  ███░░░░░███   ███░░░░░███░█░░░███░░░█
 ░███    ░███  ░███  █ ░  ░███    ░███  ███     ░░░ ░   ░███  ░ 
 ░██████████   ░██████    ░███████████ ░███             ░███    
 ░███░░░░░███  ░███░░█    ░███░░░░░███ ░███             ░███    
 ░███    ░███  ░███ ░   █ ░███    ░███ ░░███     ███    ░███    
 █████   █████ ██████████ █████   █████ ░░█████████     █████   
░░░░░   ░░░░░ ░░░░░░░░░░ ░░░░░   ░░░░░   ░░░░░░░░░     ░░░░░    
    

React

Composable Go application modules built on github.com/0x626f/gioc

Overview

react provides small application building blocks for Go services that use gioc dependency injection. It includes:

• application lifecycle and cancellation context management
• logger provider configuration using github.com/0x626f/author
• environment-backed config registration and derived config providers
• reusable base service structs for context, logger, and config injection
• optional Redis, PostgreSQL, and RabbitMQ modules

Installation

go get github.com/0x626f/react

Optional subpackages are imported only when needed:

import (
    "github.com/0x626f/react"
    reactredis "github.com/0x626f/react/redis"
    reactrmq "github.com/0x626f/react/rmq"
    reactpostgres "github.com/0x626f/react/postgres"
)

Quick Example

package main

import (
    "context"
    "os"
    "syscall"

    "github.com/0x626f/author"
    "github.com/0x626f/gioc"
    "github.com/0x626f/react"
)

func main() {
    container := gioc.NewContainer()

    configModule := gioc.NewModule("Config").Global().Provide(
        gioc.ValueProvider(
            react.LoggerConfigToken,
            &react.LoggerModuleConfig{Level: author.INFO},
            true,
        ),
    )

    appModule := react.ApplicationModuleFor(react.ApplicationConfig{
        Parent:              context.Background(),
        Interruptions:       []os.Signal{os.Interrupt, syscall.SIGTERM},
        EnableShutDownHooks: true,
    })

    if err := container.AddModules(configModule, appModule, react.LoggerModule()); err != nil {
        panic(err)
    }
    if err := container.Run(); err != nil {
        panic(err)
    }

    app, err := gioc.Get[*react.ApplicationService](container, react.ApplicationContextServiceToken)
    if err != nil {
        panic(err)
    }
    app.Await()
}

Config Module

Use RegisterConfigModule to load .env files and expose a typed app config. Providers can derive module-specific configs from the root config.

package main

import (
    "github.com/0x626f/gioc"
    "github.com/0x626f/react"
    reactredis "github.com/0x626f/react/redis"
)

const AppConfigToken = gioc.Token("AppConfig")

type AppConfig struct {
    RedisURL string `env:"REDIS_URL"`
}

var ConfigModule = react.RegisterConfigModule[AppConfig](react.ConfigModuleParams[AppConfig]{
    AppConfigToken: AppConfigToken,
    LoadEnvs: []react.EnvEntry{
        {Path: ".env", Relative: true},
    },
    Providers: []react.ConfigProviders[AppConfig]{
        {
            Token: reactredis.ConfigToken,
            Provider: func(config *AppConfig) (any, error) {
                return &reactredis.Config{URL: config.RedisURL}, nil
            },
        },
    },
})

Redis Example

package main

import (
    "time"

    "github.com/0x626f/gioc"
    "github.com/0x626f/react"
    reactredis "github.com/0x626f/react/redis"
)

func resolveRedis(container *gioc.Container) (*reactredis.Service, error) {
    return gioc.Get[*reactredis.Service](container, reactredis.ServiceToken)
}

func cacheValue(service *reactredis.Service) error {
    if err := service.Set("example:key", "value", time.Minute); err != nil {
        return err
    }

    value, ok, err := service.Get("example:key")
    if err != nil || !ok {
        return err
    }

    _ = value
    return nil
}

func modules() []*gioc.Module {
    return []*gioc.Module{
        react.ApplicationModuleFor(react.ApplicationConfig{EnableShutDownHooks: true}),
        react.LoggerModule(),
        reactredis.Module,
    }
}

reactredis.ConfigToken must be provided with a *redis.Config containing URL, usually through RegisterConfigModule.

RabbitMQ Example

package main

import (
    "time"

    "github.com/0x626f/gioc"
    "github.com/0x626f/react/rmq"
    "github.com/rabbitmq/amqp091-go"
)

var rabbitMQConfig = &rmq.ModuleConfig{
    Host:        "localhost",
    Port:        5672,
    User:        "guest",
    Password:    "guest",
    VirtualHost: "operator",
}

func publish(container *gioc.Container) error {
    producer, err := gioc.Get[*rmq.ProducerService](container, rmq.ProducerServiceToken)
    if err != nil {
        return err
    }

    exchange := rmq.NewExchange("events").SetKind("direct").SetDurable(true)
    queue := rmq.NewQueue("events.created").SetDurable(true).SetBindings(
        rmq.Bind(exchange, "created")...,
    )

    service, err := gioc.Get[*rmq.Service](container, rmq.ServiceToken)
    if err != nil {
        return err
    }
    if _, err = service.CreateQueues(queue); err != nil {
        return err
    }

    producer.Bind(exchange)
    producer.WithTimeout(5 * time.Second)

    return producer.Produce(&rmq.Publication{
        Destination: "created",
        Message: amqp091.Publishing{
            ContentType: "application/json",
            Body:        []byte(`{"id":"example"}`),
        },
    })
}

Provide rmq.ModuleConfigToken with ProvideModuleConfig or a config derivation before adding rmq.Module. ModuleConfig.VirtualHost is loaded from RMQ_VIRTUAL_HOST; leave it empty to use RabbitMQ's default / virtual host. The example above connects to the operator virtual host.

PostgreSQL Example

package main

import (
    "github.com/0x626f/gioc"
    "github.com/0x626f/pgxext"
    reactpostgres "github.com/0x626f/react/postgres"
)

const UsersRepositoryToken = gioc.Token("UsersRepository")

type UsersRepository struct {
    ds *pgxext.DataSource
}

func NewUsersRepository(ds *pgxext.DataSource) *UsersRepository {
    return &UsersRepository{ds: ds}
}

var PostgresModule = reactpostgres.ForRepositories([]reactpostgres.RepositoryConstructor{
    reactpostgres.Repository(UsersRepositoryToken, NewUsersRepository),
})

Provide reactpostgres.ConfigToken with a *postgres.Config containing URL before adding the PostgreSQL module.

Testing

go test ./...

RabbitMQ integration tests are skipped unless RMQ_TEST_URL is set, for example:

RMQ_TEST_URL=amqp://guest:guest@localhost:5672 go test ./rmq -run Integration

License

MIT. See LICENSE.

Documentation

Index

• Constants
• Variables
• func ApplicationContext(ctx context.Context) gioc.IProvider
• func ApplicationModuleFor(config ApplicationConfig) *gioc.Module
• func DeriveConfig[T any, R any](originToken, targetToken gioc.Token, provider func(T) (R, error)) gioc.IProvider
• func InjectFromBase(tokens ...gioc.Token) []gioc.Token
• func Logger(config author.Config) gioc.IProvider
• func LoggerModule() *gioc.Module
• func RegisterConfigModule[T any](params ConfigModuleParams[T]) *gioc.Module
• type ApplicationConfig
• type ApplicationService
  • func (service *ApplicationService) AddHook(hook ShutDownHook)
  • func (service *ApplicationService) Await()
  • func (service *ApplicationService) DeriveContext() (context.Context, context.CancelFunc)
  • func (service *ApplicationService) Shutdown()
• type BaseConfigurableService
  • func (service *BaseConfigurableService[T]) Bootstrap(impl gioc.Token, config gioc.Token, injections gioc.Injections)
• type BaseService
  • func (service *BaseService) Bootstrap(impl gioc.Token, injections gioc.Injections)
• type ConfigModuleParams
• type ConfigProviders
• type EnvEntry
• type LoggerModuleConfig
• type ShutDownHook

Constants

const (
	ApplicationContextServiceToken = "ApplicationService"
	ApplicationContextToken        = "ApplicationContext"
)

const LoggerConfigToken gioc.Token = "LoggerConfig"

const LoggerToken = "Logger"

Variables

var BaseServiceInjections = []gioc.Token{
	ApplicationContextServiceToken,
	LoggerToken,
}

Functions

func ApplicationContext

func ApplicationContext(ctx context.Context) gioc.IProvider

func ApplicationModuleFor

func ApplicationModuleFor(config ApplicationConfig) *gioc.Module

func DeriveConfig

func DeriveConfig[T any, R any](originToken, targetToken gioc.Token, provider func(T) (R, error)) gioc.IProvider

func InjectFromBase

func InjectFromBase(tokens ...gioc.Token) []gioc.Token

func Logger

func Logger(config author.Config) gioc.IProvider

func LoggerModule

func LoggerModule() *gioc.Module

func RegisterConfigModule

func RegisterConfigModule[T any](params ConfigModuleParams[T]) *gioc.Module

Types

type ApplicationConfig

type ApplicationConfig struct {
	Parent              context.Context
	Interruptions       []os.Signal
	EnableShutDownHooks bool
}

type ApplicationService

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

func (*ApplicationService) AddHook

func (service *ApplicationService) AddHook(hook ShutDownHook)

func (*ApplicationService) Await

func (service *ApplicationService) Await()

func (*ApplicationService) DeriveContext

func (service *ApplicationService) DeriveContext() (context.Context, context.CancelFunc)

func (*ApplicationService) Shutdown

func (service *ApplicationService) Shutdown()

type BaseConfigurableService

type BaseConfigurableService[T any] struct {
	BaseService
	Config T
}

func (*BaseConfigurableService[T]) Bootstrap

func (service *BaseConfigurableService[T]) Bootstrap(impl gioc.Token, config gioc.Token, injections gioc.Injections)

type BaseService

type BaseService struct {
	Ctx  context.Context
	Stop context.CancelFunc

	ApplicationService *ApplicationService
	Logger             *author.Logger
}

func (*BaseService) Bootstrap

func (service *BaseService) Bootstrap(impl gioc.Token, injections gioc.Injections)

type ConfigModuleParams

type ConfigModuleParams[T any] struct {
	AppConfigToken gioc.Token
	LoadEnvs       []EnvEntry
	Providers      []ConfigProviders[T]
}

type ConfigProviders

type ConfigProviders[T any] struct {
	Token    gioc.Token
	Provider func(*T) (any, error)
}

type EnvEntry

type EnvEntry struct {
	Path     string
	Relative bool
}

type LoggerModuleConfig

type LoggerModuleConfig struct {
	Level author.LogLevel `env:"LOG_LEVEL"`
}

type ShutDownHook

type ShutDownHook func()