daemon

Documentation

Overview

Package daemon provides a Kubernetes-native daemon runtime with graceful lifecycle management. This package enables building long-running services with health checks, task management, and graceful shutdown handling.

Index

• type Config
  • func DefaultConfig() Config
• type Daemon
  • func New(cfg Config) *Daemon
  • func (d *Daemon) IsReady() bool
  • func (d *Daemon) RegisterTask(t Task)
  • func (d *Daemon) Run(ctx context.Context) error
  • func (d *Daemon) SetReady(ready bool)
• type Job
• type Scheduler
  • func NewScheduler(logger *slog.Logger) *Scheduler
  • func (s *Scheduler) AddJob(name string, schedule string, fn func(ctx context.Context) error) error
  • func (s *Scheduler) AddJobWithInterval(name string, interval time.Duration, fn func(ctx context.Context) error) error
  • func (s *Scheduler) GetNextRun(jobName string) (time.Time, bool)
  • func (s *Scheduler) IsRunning() bool
  • func (s *Scheduler) JobCount() int
  • func (s *Scheduler) Name() string
  • func (s *Scheduler) Start(ctx context.Context) error
  • func (s *Scheduler) Stop(ctx context.Context) error
• type Task

Types

type Config

type Config struct {
	// HealthPort is the port for health check endpoints (default: 9090)
	HealthPort int
	// ShutdownTimeout is the maximum time to wait for graceful shutdown
	ShutdownTimeout time.Duration
	// Logger is the structured logger to use
	Logger *slog.Logger
}

Config holds daemon configuration.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns sensible defaults.

type Daemon

type Daemon struct {
	// contains filtered or unexported fields
}

Daemon manages the lifecycle of a long-running service.

func New

func New(cfg Config) *Daemon

New creates a new Daemon with the given configuration.

func (*Daemon) IsReady

func (d *Daemon) IsReady() bool

IsReady returns whether the daemon is ready.

func (*Daemon) RegisterTask

func (d *Daemon) RegisterTask(t Task)

RegisterTask adds a task to be managed by the daemon.

func (*Daemon) Run

func (d *Daemon) Run(ctx context.Context) error

Run starts the daemon and blocks until shutdown signal is received.

func (*Daemon) SetReady

func (d *Daemon) SetReady(ready bool)

SetReady marks the daemon as ready to receive traffic.

type Job

type Job struct {
	Name     string
	Schedule string // cron expression (e.g., "0 */6 * * *" for every 6 hours)
	Fn       func(ctx context.Context) error
}

Job represents a scheduled job.

type Scheduler

type Scheduler struct {
	// contains filtered or unexported fields
}

Scheduler manages periodic job execution using cron expressions.

func NewScheduler

func NewScheduler(logger *slog.Logger) *Scheduler

NewScheduler creates a scheduler with the given logger.

func (*Scheduler) AddJob

func (s *Scheduler) AddJob(name string, schedule string, fn func(ctx context.Context) error) error

AddJob adds a job with a cron expression. Cron expressions support 6 fields: second minute hour day month weekday Examples:

• "0 0 */6 * * *" - every 6 hours at minute 0, second 0
• "0 0 0 * * *" - daily at midnight
• "0 */30 * * * *" - every 30 minutes
• "@every 1h" - every hour (robfig/cron shorthand)
• "@daily" - once a day at midnight

func (*Scheduler) AddJobWithInterval

func (s *Scheduler) AddJobWithInterval(name string, interval time.Duration, fn func(ctx context.Context) error) error

AddJobWithInterval adds a job that runs at a fixed interval. This is a convenience method that converts the interval to a cron expression.

func (*Scheduler) GetNextRun

func (s *Scheduler) GetNextRun(jobName string) (time.Time, bool)

GetNextRun returns the next scheduled run time for a job.

func (*Scheduler) IsRunning

func (s *Scheduler) IsRunning() bool

IsRunning returns whether the scheduler is currently running.

func (*Scheduler) JobCount

func (s *Scheduler) JobCount() int

JobCount returns the number of registered jobs.

func (*Scheduler) Name

func (s *Scheduler) Name() string

Name implements Task interface.

func (*Scheduler) Start

func (s *Scheduler) Start(ctx context.Context) error

Start implements Task interface - starts the cron scheduler.

func (*Scheduler) Stop

func (s *Scheduler) Stop(ctx context.Context) error

Stop implements Task interface.

type Task

type Task interface {
	// Name returns a human-readable name for logging
	Name() string
	// Start begins the task. It should block until ctx is cancelled.
	Start(ctx context.Context) error
	// Stop performs cleanup. Called after Start returns.
	Stop(ctx context.Context) error
}

Task represents a background task managed by the daemon.