96 lines
2.8 KiB
Markdown
96 lines
2.8 KiB
Markdown
---
|
|
title: Core Go Framework
|
|
description: Dependency injection and service lifecycle framework for Go.
|
|
---
|
|
|
|
# Core Go Framework
|
|
|
|
Core (`forge.lthn.ai/core/go`) is a dependency injection and service lifecycle framework for Go. It provides a typed service registry, lifecycle hooks, and a message-passing bus for decoupled communication between services.
|
|
|
|
This is the foundation layer of the ecosystem. It has no CLI, no GUI, and minimal dependencies.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
go get forge.lthn.ai/core/go
|
|
```
|
|
|
|
Requires Go 1.26 or later.
|
|
|
|
## What It Does
|
|
|
|
Core solves three problems that every non-trivial Go application eventually faces:
|
|
|
|
1. **Service wiring** -- how do you register, retrieve, and type-check services without import cycles?
|
|
2. **Lifecycle management** -- how do you start and stop services in the right order?
|
|
3. **Decoupled communication** -- how do services talk to each other without knowing each other's types?
|
|
|
|
## Packages
|
|
|
|
| Package | Purpose |
|
|
|---------|---------|
|
|
| [`pkg/core`](services.md) | DI container, service registry, lifecycle, message bus |
|
|
| `pkg/log` | Structured logger service with Core integration |
|
|
|
|
## Quick Example
|
|
|
|
```go
|
|
package main
|
|
|
|
import (
|
|
"context"
|
|
"fmt"
|
|
|
|
"forge.lthn.ai/core/go/pkg/core"
|
|
"forge.lthn.ai/core/go/pkg/log"
|
|
)
|
|
|
|
func main() {
|
|
c, err := core.New(
|
|
core.WithName("log", log.NewService(log.Options{Level: log.LevelInfo})),
|
|
core.WithServiceLock(), // Prevent late registration
|
|
)
|
|
if err != nil {
|
|
panic(err)
|
|
}
|
|
|
|
// Start all services
|
|
if err := c.ServiceStartup(context.Background(), nil); err != nil {
|
|
panic(err)
|
|
}
|
|
|
|
// Type-safe retrieval
|
|
logger, err := core.ServiceFor[*log.Service](c, "log")
|
|
if err != nil {
|
|
panic(err)
|
|
}
|
|
fmt.Println("Log level:", logger.Level())
|
|
|
|
// Shut down (reverse order)
|
|
_ = c.ServiceShutdown(context.Background())
|
|
}
|
|
```
|
|
|
|
## Documentation
|
|
|
|
| Page | Covers |
|
|
|------|--------|
|
|
| [Getting Started](getting-started.md) | Creating a Core app, registering your first service |
|
|
| [Services](services.md) | Service registration, `ServiceRuntime`, factory pattern |
|
|
| [Lifecycle](lifecycle.md) | `Startable`/`Stoppable` interfaces, startup/shutdown order |
|
|
| [Messaging](messaging.md) | ACTION, QUERY, PERFORM -- the message bus |
|
|
| [Configuration](configuration.md) | `WithService`, `WithName`, `WithAssets`, `WithServiceLock` options |
|
|
| [Testing](testing.md) | Test naming conventions, test helpers, fuzz testing |
|
|
| [Errors](errors.md) | `E()` helper, `Error` struct, unwrapping |
|
|
|
|
## Dependencies
|
|
|
|
Core is deliberately minimal:
|
|
|
|
- `forge.lthn.ai/core/go-io` -- abstract storage (local, S3, SFTP, WebDAV)
|
|
- `forge.lthn.ai/core/go-log` -- structured logging
|
|
- `github.com/stretchr/testify` -- test assertions (test-only)
|
|
|
|
## Licence
|
|
|
|
EUPL-1.2
|