go-project-starter-runtime

Runtime library for projects generated by go-project-starter.

Overview

This library contains the runtime components that were previously generated as part of the pkg/ directory. By extracting these components into a separate dependency, we:

• Reduce code duplication across generated projects
• Enable updates to runtime components without regenerating projects
• Provide a stable, versioned API for common functionality

Installation

go get github.com/Educentr/go-project-starter-runtime

Packages

Core Interfaces (pkg/ds)

• IService - Service interface
• Runnable - Components that can run and gracefully stop
• Actor, Authorizer - Authentication/authorization abstractions
• ServerBucket - Server management

Models (pkg/model/actor)

• Actor implementation for authentication

Request Context (pkg/reqctx)

• Context management utilities
• Request metadata handling
• Cumulative metrics tracking
• Logger context integration via callback interface

Application Core (pkg/app)

• Application lifecycle management
• Health checks (healthstate)
• Service authentication (serviceauth)
• Metrics collection (metrics)
• Graceful shutdown (closer)

Transports

• REST (pkg/app/rest) - HTTP server with middleware (auth, metrics, tracing, CSRF)
• gRPC (pkg/app/grpc) - gRPC server implementation
• Telegram (pkg/drivers/telegram) - Telegram bot driver

Service Metrics (pkg/servicemetrics)

• Service-level metrics interface

Logger Integration

The runtime library is logger-agnostic. For logger context integration (e.g., adding ActorUID, RequestID to logs), implement the LoggerContextUpdater interface:

import (
    "github.com/Educentr/go-project-starter-runtime/pkg/reqctx"
    zlog "github.com/rs/zerolog"
)

type zerologUpdater struct{}

func (z *zerologUpdater) UpdateContext(ctx context.Context, update func(reqctx.LoggerContext) reqctx.LoggerContext) context.Context {
    return zlog.Ctx(ctx).UpdateContext(func(c zlog.Context) zlog.Context {
        adapter := &zerologAdapter{c}
        updated := update(adapter)
        return updated.(*zerologAdapter).ctx
    })
}

// Register in main():
func main() {
    reqctx.SetLoggerUpdater(&zerologUpdater{})
    // ...
}

Versioning

This project follows Semantic Versioning:

• v0.x.x - Development versions (API may change)
• v1.x.x - Stable API
• v2.x.x+ - Breaking changes with migration guides

Requirements

• Go 1.21+

Dependencies

• github.com/rs/zerolog - Structured logging
• github.com/prometheus/client_golang - Metrics
• github.com/Educentr/go-onlineconf - Configuration management
• github.com/go-telegram-bot-api/telegram-bot-api/v5 - Telegram bot API

Development

# Run tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Lint
golangci-lint run

License

MIT License - see LICENSE file for details.

Related Projects

• go-project-starter - Project generator that uses this runtime