serviceapi

Documentation

Index

• Constants
• func GetService[T any](regCtx registration.Context, name string) (T, error)
• type CommandResult
  • func NewCommandResult(fnRowsAffected func() int64) CommandResult
• type CommandResultImpl
  • func (c *CommandResultImpl) RowsAffected() int64
• type DbConn
• type DbExecutor
• type DbPool
• type DbTx
• type HealthCheck
• type HealthChecker
• type HealthResult
• type HealthService
• type HealthStatus
• type HttpListener
• type I18n
• type KvStore
• type Labels
• type LogFields
• type LogLevel
  • func ParseLogLevelSafe(levelStr string) (LogLevel, bool)
  • func (l LogLevel) String() string
• type Logger
• type Metrics
• type Redis
• type RouterEngine
• type Row
• type RowMap
• type Rows
• type RpcServer

Constants

const ConfigKeyLogFormat = "log_format"

const ConfigKeyLogLevel = "log_level"

const ConfigKeyLogOutput = "log_output"

const HTTP_LISTENER_PREFIX string = "lokstra.http_listener."

const HTTP_ROUTER_PREFIX string = "lokstra.http_router."

Functions

func GetService

func GetService[T any](regCtx registration.Context, name string) (T, error)

Types

type CommandResult

type CommandResult interface {
	RowsAffected() int64
}

CommandResult abstracts result from Exec()

func NewCommandResult

func NewCommandResult(fnRowsAffected func() int64) CommandResult

type CommandResultImpl

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

func (*CommandResultImpl) RowsAffected

func (c *CommandResultImpl) RowsAffected() int64

RowsAffected implements CommandResult.

type DbConn

type DbConn interface {
	Begin(ctx context.Context) (DbTx, error)
	Transaction(ctx context.Context, fn func(tx DbExecutor) error) error

	Release() error
	DbExecutor
}

DbConn represents a live DB connection (e.g. from pgxpool)

type DbExecutor

type DbExecutor interface {
	Exec(ctx context.Context, query string, args ...any) (CommandResult, error)
	Query(ctx context.Context, query string, args ...any) (Rows, error)
	QueryRow(ctx context.Context, query string, args ...any) Row

	SelectOne(ctx context.Context, query string, args []any, dest ...any) error
	SelectMustOne(ctx context.Context, query string, args []any, dest ...any) error

	SelectOneRowMap(ctx context.Context, query string, args ...any) (RowMap, error)
	SelectManyRowMap(ctx context.Context, query string, args ...any) ([]RowMap, error)

	SelectManyWithMapper(ctx context.Context,
		fnScan func(Row) (any, error), query string, args ...any) (any, error)

	IsExists(ctx context.Context, query string, args ...any) (bool, error)
	IsErrorNoRows(err error) bool
}

type DbPool

type DbPool interface {
	Acquire(ctx context.Context, schema string) (DbConn, error)
}

DbPool defines a connection pool interface supporting schema-aware connection acquisition and future multi-backend support.

type DbTx

type DbTx interface {
	Commit(ctx context.Context) error
	Rollback(ctx context.Context) error
	DbExecutor
}

DbTx represents an ongoing transaction

type HealthCheck

type HealthCheck struct {
	Name      string         `json:"name"`
	Status    HealthStatus   `json:"status"`
	Message   string         `json:"message,omitempty"`
	Details   map[string]any `json:"details,omitempty"`
	Duration  time.Duration  `json:"duration"`
	CheckedAt time.Time      `json:"checked_at"`
	Error     string         `json:"error,omitempty"`
}

HealthCheck represents a single health check result

type HealthChecker

type HealthChecker func(ctx context.Context) HealthCheck

HealthChecker defines a function that performs a health check

type HealthResult

type HealthResult struct {
	Status    HealthStatus           `json:"status"`
	Checks    map[string]HealthCheck `json:"checks"`
	Duration  time.Duration          `json:"duration"`
	CheckedAt time.Time              `json:"checked_at"`
}

HealthResult represents the overall health check result

type HealthService

type HealthService interface {
	service.Service

	// RegisterCheck registers a health check with a name
	RegisterCheck(name string, checker HealthChecker)

	// UnregisterCheck removes a health check
	UnregisterCheck(name string)

	// CheckHealth performs all registered health checks
	CheckHealth(ctx context.Context) HealthResult

	// CheckHealthWithTimeout performs health checks with a timeout
	CheckHealthWithTimeout(timeout time.Duration) HealthResult

	// IsHealthy returns true if all checks are healthy
	IsHealthy(ctx context.Context) bool

	// GetCheck performs a specific health check by name
	GetCheck(ctx context.Context, name string) (HealthCheck, bool)

	// ListChecks returns all registered check names
	ListChecks() []string
}

HealthService provides health checking capabilities for Kubernetes and monitoring

type HealthStatus

type HealthStatus string

HealthStatus represents the health status of a component

const (
	HealthStatusHealthy   HealthStatus = "healthy"
	HealthStatusDegraded  HealthStatus = "degraded"
	HealthStatusUnhealthy HealthStatus = "unhealthy"
)

type HttpListener

type HttpListener interface {
	// ListenAndServe starts the HTTP server on the specified address.
	// It returns an error if the server fails to start.
	ListenAndServe(addr string, handler http.Handler) error
	// Shutdown gracefully stops the HTTP server.
	// It waits for all active requests to finish before shutting down.
	Shutdown(shutdownTimeout time.Duration) error
	// IsRunning checks if the HTTP server is currently running.
	IsRunning() bool
	// ActiveRequest returns the number of currently active requests.
	ActiveRequest() int

	// GetStartMessage returns a message indicating where the server is listening.
	GetStartMessage(addr string) string
}

type I18n

type I18n interface {
	T(lang, code string, params map[string]any) string
}

type KvStore

type KvStore interface {
	// Set sets a value with a key and optional TTL.
	Set(ctx context.Context, key string, value any, ttl time.Duration) error

	// Get retrieves a value by key.
	Get(ctx context.Context, key string, dest any) error

	// Delete removes a single key.
	Delete(ctx context.Context, key string) error

	// Deletes multiple keys.
	DeleteKeys(ctx context.Context, keys ...string) error

	// Gets all keys matching the pattern.
	Keys(ctx context.Context, pattern string) ([]string, error)
}

type Labels

type Labels = map[string]string

type LogFields

type LogFields = map[string]any

type LogLevel

type LogLevel int

const (
	LogLevelDebug LogLevel = iota
	LogLevelInfo
	LogLevelWarn
	LogLevelError
	LogLevelFatal
	LogLevelDisabled
)

func ParseLogLevelSafe

func ParseLogLevelSafe(levelStr string) (LogLevel, bool)

func (LogLevel) String

func (l LogLevel) String() string

type Logger

type Logger interface {
	Debugf(msg string, v ...any)
	Infof(msg string, v ...any)
	Warnf(msg string, v ...any)
	Errorf(msg string, v ...any)
	Fatalf(msg string, v ...any)

	GetLogLevel() LogLevel
	SetLogLevel(level LogLevel)
	WithField(key string, value any) Logger
	WithFields(fields LogFields) Logger

	SetFormat(format string)
	SetOutput(output string)
}

Logger defines logging interface used across services

type Metrics

type Metrics interface {
	IncCounter(name string, labels Labels)
	ObserveHistogram(name string, value float64, labels Labels)
	SetGauge(name string, value float64, labels Labels)
}

type Redis

type Redis interface {
	Client() *redis.Client
}

type RouterEngine

type RouterEngine interface {
	// HandleMethod registers a handler for a specific HTTP method and path.
	HandleMethod(method request.HTTPMethod, path string, handler http.Handler)

	ServeHTTP(w http.ResponseWriter, r *http.Request)

	RawHandle(pattern string, handler http.Handler)
	RawHandleFunc(pattern string, handlerFunc http.HandlerFunc)

	ServeStatic(prefix string, spa bool, sources ...fs.FS)
	ServeReverseProxy(prefix string, handler http.HandlerFunc)

	// Assume sources has:
	//   - "/layouts" for HTML layout templates
	//   - "/pages" for HTML page templates
	//
	// All Request paths will be treated as page requests,
	ServeHtmxPage(pageDataRouter http.Handler, prefix string,
		si *static_files.ScriptInjection, sources ...fs.FS)
}

RouterEngine defines the interface for a router engine that can handle HTTP methods, serve static files, HTMX Page, and reverse proxies.

type Row

type Row interface {
	Scan(dest ...any) error
}

Row abstracts single row result from QueryRow()

type RowMap

type RowMap = map[string]any

type Rows

type Rows interface {
	Next() bool
	Scan(dest ...any) error
	Close() error
	Err() error
}

Rows abstracts rows from Query()

type RpcServer

type RpcServer interface {
	HandleRequest(ctx *request.Context, service service.Service, MethodName string) error
}