README
¶
About
fire is a small library for coordinating long-running application components such as:
- HTTP servers
- gRPC servers
- consumers
- workers
- schedulers
- background services
Unlike errgroup, fire separates lifecycle from error policy.
Instead of assuming that every error should terminate the application, every task may decide what should happen next.
Concepts
Everything in fire is built from only three primitives.
Task
A Task is anything executable.
fire.Sync(func() error)
fire.Async(func() Task)
Tasks may transform or suppress errors using handlers.
t := fire.Sync(run)
t.IfError(func(err error) error {
return fmt.Errorf("server: %w", err)
})
// or
t := fire.Sync(run)
t.Handle(func(err error) error {
if err != nil {
return fmt.Errorf("server: %w", err)
}
return nil
})
Component
A Component represents something with a start and stop phase.
component := fire.NewComponent()
component.Start = fire.Sync(server.ListenAndServe)
component.Stop = fire.SyncWithContext(server.Shutdown)
When Start finishes, the component automatically cancels itself, allowing Stop to execute.
Group
A Group runs multiple tasks concurrently.
g := fire.NewGroup()
g.Add(task1)
g.Add(task2)
g.Wait(ctx)
All tasks share the same context.
Calling
g.Cancel()
cancels every task in a group.
Example
ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGINT, syscall.SIGTERM)
defer cancel()
server1 := NewServer("0.0.0.0:1111")
server2 := NewServer("0.0.0.0:2222")
g := fire.NewGroup()
t := fire.Async(server1.Run)
t.IfError(func(err error) error {
return fmt.Errorf("failed to run server1: %w", err)
})
g.Add(t)
t = fire.Async(server2.Run)
t.IfError(func(err error) error {
return fmt.Errorf("failed to run server2: %w", err)
})
g.Add(t)
g.Wait(ctx)
Why fire?
Without fire, lifecycle code usually consists of:
- goroutines
- WaitGroups
- channels
- signal handling
- context cancellation
- shutdown ordering
fire keeps this orchestration in reusable primitives while leaving application-specific error decisions to the caller.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Component ¶ added in v1.0.1
Component represents a long-running service with separate start and stop phases.
func NewComponent ¶ added in v1.0.1
func NewComponent() *Component
NewComponent creates an empty component.
func (*Component) Cancel ¶ added in v1.0.1
func (c *Component) Cancel()
Cancel requests the component to stop.
func (*Component) Handle ¶ added in v1.0.1
func (c *Component) Handle(h handler)
Handle registers a component error handler.
Errors from both Start and Stop are passed through the registered handler.
type Group ¶
type Group struct {
// contains filtered or unexported fields
}
Group runs multiple tasks concurrently under a shared context.
A Group propagates context cancellation to all registered tasks and waits until every task has completed.
Error handling is configurable through task and group handlers.
func (*Group) Cancel ¶
func (g *Group) Cancel()
Cancel cancels the group's context.
Calling Cancel causes every running task that observes the context to begin shutting down.
func (*Group) Handle ¶ added in v1.0.1
func (g *Group) Handle(h handler)
Handle registers an error handler.
Every error produced by child tasks is passed through the registered handler.
type Task ¶ added in v1.0.1
type Task interface {
IfError(handler)
Handle(handler)
// contains filtered or unexported methods
}
Task represents an executable unit managed by fire.
func AsyncWithContext ¶ added in v1.0.1
func AsyncWithContext(f functionAsync) Task
AsyncWithContext wraps a context-aware task factory.
func SyncWithContext ¶ added in v1.0.1
func SyncWithContext(f functionSync) Task
SyncWithContext wraps a context-aware function into a Task.
Source Files