2d52b83f60
Codex-authored docs covering primitives, commands, messaging, lifecycle, subsystems, and getting started — all using the current DTO/Options/Result API with concrete usage examples. Co-Authored-By: Virgil <virgil@lethean.io>
151 lines
3.5 KiB
Markdown
151 lines
3.5 KiB
Markdown
# CoreGO
|
|
|
|
Dependency injection, service lifecycle, command routing, and message-passing for Go.
|
|
|
|
Import path:
|
|
|
|
```go
|
|
import "dappco.re/go/core"
|
|
```
|
|
|
|
CoreGO is the foundation layer for the Core ecosystem. It gives you:
|
|
|
|
- one container: `Core`
|
|
- one input shape: `Options`
|
|
- one output shape: `Result`
|
|
- one command tree: `Command`
|
|
- one message bus: `ACTION`, `QUERY`, `PERFORM`
|
|
|
|
## Why It Exists
|
|
|
|
Most non-trivial Go systems end up needing the same small set of infrastructure:
|
|
|
|
- a place to keep runtime state and shared subsystems
|
|
- a predictable way to start and stop managed components
|
|
- a clean command surface for CLI-style workflows
|
|
- decoupled communication between components without tight imports
|
|
|
|
CoreGO keeps those pieces small and explicit.
|
|
|
|
## Quick Example
|
|
|
|
```go
|
|
package main
|
|
|
|
import (
|
|
"context"
|
|
"fmt"
|
|
|
|
"dappco.re/go/core"
|
|
)
|
|
|
|
type flushCacheTask struct {
|
|
Name string
|
|
}
|
|
|
|
func main() {
|
|
c := core.New(core.Options{
|
|
{Key: "name", Value: "agent-workbench"},
|
|
})
|
|
|
|
c.Service("cache", core.Service{
|
|
OnStart: func() core.Result {
|
|
core.Info("cache started", "app", c.App().Name)
|
|
return core.Result{OK: true}
|
|
},
|
|
OnStop: func() core.Result {
|
|
core.Info("cache stopped", "app", c.App().Name)
|
|
return core.Result{OK: true}
|
|
},
|
|
})
|
|
|
|
c.RegisterTask(func(_ *core.Core, task core.Task) core.Result {
|
|
switch t := task.(type) {
|
|
case flushCacheTask:
|
|
return core.Result{Value: "cache flushed for " + t.Name, OK: true}
|
|
}
|
|
return core.Result{}
|
|
})
|
|
|
|
c.Command("cache/flush", core.Command{
|
|
Action: func(opts core.Options) core.Result {
|
|
return c.PERFORM(flushCacheTask{
|
|
Name: opts.String("name"),
|
|
})
|
|
},
|
|
})
|
|
|
|
if !c.ServiceStartup(context.Background(), nil).OK {
|
|
panic("startup failed")
|
|
}
|
|
|
|
r := c.Cli().Run("cache", "flush", "--name=session-store")
|
|
fmt.Println(r.Value)
|
|
|
|
_ = c.ServiceShutdown(context.Background())
|
|
}
|
|
```
|
|
|
|
## Core Surfaces
|
|
|
|
| Surface | Purpose |
|
|
|---------|---------|
|
|
| `Core` | Central container and access point |
|
|
| `Service` | Managed lifecycle component |
|
|
| `Command` | Path-based executable operation |
|
|
| `Cli` | CLI surface over the command tree |
|
|
| `Data` | Embedded filesystem mounts |
|
|
| `Drive` | Named transport handles |
|
|
| `Fs` | Local filesystem operations |
|
|
| `Config` | Runtime settings and feature flags |
|
|
| `I18n` | Locale collection and translation delegation |
|
|
| `E`, `Wrap`, `ErrorLog`, `ErrorPanic` | Structured failures and panic recovery |
|
|
|
|
## AX-Friendly Model
|
|
|
|
CoreGO follows the same design direction as the AX spec:
|
|
|
|
- predictable names over compressed names
|
|
- paths as documentation, such as `deploy/to/homelab`
|
|
- one repeated vocabulary across the framework
|
|
- examples that show how to call real APIs
|
|
|
|
## Install
|
|
|
|
```bash
|
|
go get dappco.re/go/core
|
|
```
|
|
|
|
Requires Go 1.26 or later.
|
|
|
|
## Test
|
|
|
|
```bash
|
|
core go test
|
|
```
|
|
|
|
Or with the standard toolchain:
|
|
|
|
```bash
|
|
go test ./...
|
|
```
|
|
|
|
## Docs
|
|
|
|
The full documentation set lives in `docs/`.
|
|
|
|
| Path | Covers |
|
|
|------|--------|
|
|
| `docs/getting-started.md` | First runnable CoreGO app |
|
|
| `docs/primitives.md` | `Options`, `Result`, `Service`, `Message`, `Query`, `Task` |
|
|
| `docs/services.md` | Service registry, runtime helpers, service locks |
|
|
| `docs/commands.md` | Path-based commands and CLI execution |
|
|
| `docs/messaging.md` | `ACTION`, `QUERY`, `QUERYALL`, `PERFORM`, `PerformAsync` |
|
|
| `docs/lifecycle.md` | Startup, shutdown, context, and task draining |
|
|
| `docs/subsystems.md` | `App`, `Data`, `Drive`, `Fs`, `I18n`, `Cli` |
|
|
| `docs/errors.md` | Structured errors, logging helpers, panic recovery |
|
|
| `docs/testing.md` | Test naming and framework testing patterns |
|
|
|
|
## License
|
|
|
|
EUPL-1.2
|