https://github.com/z5labs/bedrock
A framework for building other frameworks
https://github.com/z5labs/bedrock
framework go golang
Last synced: about 1 month ago
JSON representation
A framework for building other frameworks
- Host: GitHub
- URL: https://github.com/z5labs/bedrock
- Owner: z5labs
- License: mit
- Created: 2023-07-25T03:56:36.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2026-02-04T01:07:44.000Z (about 1 month ago)
- Last Synced: 2026-02-04T11:32:30.514Z (about 1 month ago)
- Topics: framework, go, golang
- Language: Go
- Homepage:
- Size: 782 KB
- Stars: 15
- Watchers: 0
- Forks: 1
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- fucking-awesome-go - bedrock - Provides a minimal, modular and composable foundation for quickly developing services and more use case specific frameworks in Go. (Distributed Systems / Search and Analytic Databases)
- awesome-go-cn - bedrock
- awesome-go-with-stars - bedrock - 03-03 | (Distributed Systems / Search and Analytic Databases)
- awesome-go-cn - bedrock
- awesome-go - bedrock - Provides a minimal, modular and composable foundation for quickly developing services and more use case specific frameworks in Go. (Distributed Systems / Search and Analytic Databases)
- awesome-go - bedrock - Provides a minimal, modular and composable foundation for quickly developing services and more use case specific frameworks in Go. (Distributed Systems / Search and Analytic Databases)
- awesome-go-plus - bedrock - Provides a minimal, modular and composable foundation for quickly developing services and more use case specific frameworks in Go.  (Distributed Systems / Search and Analytic Databases)
- awesome-go - bedrock - Provides a minimal, modular and composable foundation for quickly developing services and more use case specific frameworks in Go. (Distributed Systems / Search and Analytic Databases)
README
# bedrock
[](https://github.com/avelino/awesome-go)
[](https://pkg.go.dev/github.com/z5labs/bedrock)
[](https://goreportcard.com/report/github.com/z5labs/bedrock)
[](https://github.com/z5labs/bedrock/actions/workflows/build.yaml)
**bedrock provides a minimal, modular and composable foundation for
quickly developing more use case specific frameworks in Go.**
# Building custom frameworks with bedrock
One of the guiding principals for [bedrock](https://pkg.go.dev/github.com/z5labs/bedrock) is to be composable.
This principal comes from the experience gained from working with custom, tailor made frameworks which
over their lifetime within an organization are unable to adapt to changing
development and deployment patterns. Eventually, these frameworks are abandoned
for new ones or completely rewritten to reflect the current state of the organization.
[bedrock](https://pkg.go.dev/github.com/z5labs/bedrock) defines a small set of types and carefully
chooses its opinions to balance composability and functionality, as much as it can. The result is, in fact, a framework
that isn't necessarily designed for building services directly, but instead meant for building
more custom, use case specific frameworks.
For example, [bedrock](https://pkg.go.dev/github.com/z5labs/bedrock) could be used by your organizations
platform engineering or framework team(s) to quickly develop internal frameworks which abstract over all of
your organizations requirements e.g. OpenTelemetry, Logging, Authenticated endpoints, etc. Then, due to the
high composibility of [bedrock](https://pkg.go.dev/github.com/z5labs/bedrock), any changes within your
organization would then be very easy to adapt to within your internal framework.
## Core Concepts
### Builder
```go
type Builder[T any] interface {
Build(context.Context) (T, error)
}
```
[Builder](https://pkg.go.dev/github.com/z5labs/bedrock#Builder) is a
generic interface for constructing application components with context support.
Builders can be composed using functional combinators like
[Map](https://pkg.go.dev/github.com/z5labs/bedrock#Map) and
[Bind](https://pkg.go.dev/github.com/z5labs/bedrock#Bind).
### Runtime
```go
type Runtime interface {
Run(context.Context) error
}
```
[Runtime](https://pkg.go.dev/github.com/z5labs/bedrock#Runtime) is a
simple abstraction over the execution of your specific application type
e.g. HTTP server, gRPC server, background worker, etc.
### Runner
```go
type Runner[T Runtime] interface {
Run(context.Context, Builder[T]) error
}
```
[Runner](https://pkg.go.dev/github.com/z5labs/bedrock#Runner) executes
application components built from Builders. Runners can be wrapped to add
cross-cutting concerns like signal handling with
[NotifyOnSignal](https://pkg.go.dev/github.com/z5labs/bedrock#NotifyOnSignal)
and panic recovery with
[RecoverPanics](https://pkg.go.dev/github.com/z5labs/bedrock#RecoverPanics).
### Configuration
```go
package config
type Reader[T any] interface {
Read(context.Context) (Value[T], error)
}
```
The [config.Reader](https://pkg.go.dev/github.com/z5labs/bedrock/config#Reader) is
arguably the most powerful abstraction defined in any of the [bedrock](https://pkg.go.dev/github.com/z5labs/bedrock)
packages. It abstracts over reading configuration values that may or may not be present,
distinguishing between "not set" and "set to zero value." Readers can be composed using
functional combinators like
[Or](https://pkg.go.dev/github.com/z5labs/bedrock/config#Or),
[Map](https://pkg.go.dev/github.com/z5labs/bedrock/config#Map),
[Bind](https://pkg.go.dev/github.com/z5labs/bedrock/config#Bind), and
[Default](https://pkg.go.dev/github.com/z5labs/bedrock/config#Default).
## Putting them altogether
Below is a tiny and simplistic example of all the core concepts of [bedrock](https://pkg.go.dev/github.com/z5labs/bedrock).
### main.go
```go
package main
import (
"context"
"log/slog"
"os"
"syscall"
"github.com/z5labs/bedrock"
"github.com/z5labs/bedrock/config"
)
func main() {
os.Exit(run())
}
func run() int {
// Create a runner with signal handling and panic recovery
runner := bedrock.NotifyOnSignal(
bedrock.RecoverPanics(
bedrock.DefaultRunner[bedrock.Runtime](),
),
os.Interrupt,
os.Kill,
syscall.SIGTERM,
)
// Build and run the application
err := runner.Run(
context.Background(),
bedrock.BuilderFunc[bedrock.Runtime](buildApp),
)
if err == nil {
return 0
}
return 1
}
type myApp struct {
log *slog.Logger
}
// buildApp constructs the application using functional config composition
func buildApp(ctx context.Context) (bedrock.Runtime, error) {
// Read log level from environment with a default
logLevelReader := config.Default(
"INFO",
config.Env("MIN_LOG_LEVEL"),
)
logLevel, err := config.Read(ctx, logLevelReader)
if err != nil {
return nil, err
}
// Parse the log level string
var level slog.Level
err = level.UnmarshalText([]byte(logLevel))
if err != nil {
return nil, err
}
return &myApp{
log: slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
Level: level,
})),
}, nil
}
// Run implements the bedrock.Runtime interface.
func (a *myApp) Run(ctx context.Context) error {
// Do something here like:
// - run an HTTP server
// - start the AWS lambda runtime,
// - run goroutines to consume from Kafka
// etc.
a.log.InfoContext(ctx, "running my app")
return nil
}
```
# Built with bedrock
- [z5labs/humus](https://github.com/z5labs/humus)