hostkit

README

hostkit

hostkit coordinates the lifecycle of one host-owned Service. It uses only the Go standard library and keeps process policy separate from the components owned by a concrete host.

Lifecycle contract

A Service synchronously starts, exposes one stable terminal channel, stops intake during drain, cancels and reconciles active work during force stop, and releases resources during close:

package example

import (
	"context"
	"fmt"
	"time"

	"github.com/eruca/goagents/hostkit"
)

func run(
	ctx context.Context,
	service hostkit.Service,
	interrupts <-chan struct{},
) hostkit.Result {
	result := hostkit.Run(ctx, service, interrupts, hostkit.Options{
		DrainTimeout:   30 * time.Second,
		CleanupTimeout: 5 * time.Second,
	})
	if result.Err() != nil {
		fmt.Printf("%s: %v\n", result.Code(), result.Err())
	}
	return result
}

Start must not reuse its context as the execution root. Done must return the same read-only channel on every call and report one terminal result. Drain stops intake and waits for active work. ForceStop cancels active work and performs host-owned reconciliation. Close releases resources after active work can no longer use them.

Result has no writable outcome fields. A zero result means success; ExitCode(), Code(), and Err() expose the normalized outcome. A service uses Fail to classify a safe public message while retaining the original cause for errors.Is.

Code	Exit
success (empty code)	0
internal_error	1
config_failed	2
initialization_failed	2
listen_failed	3
serve_failed	4
shutdown_timeout	5
shutdown_cleanup_timeout	5

The first interrupt starts Drain with DrainTimeout. A second interrupt cancels the remaining drain wait and enters force stop; it does not skip cleanup. ForceStop and Close share one CleanupTimeout deadline. If force stop does not return before that deadline, hostkit does not call Close concurrently and returns shutdown_cleanup_timeout.

hostkit does not manage workflows, HTTP servers, operating-system signal constants, participant graphs, or external side effects. The host adapter owns those policies and translates signals into the generic interrupt channel.

Documentation

Index

• func Fail(code Code, safeMessage string, cause error) error
• func WriteError(w io.Writer, result Result) error
• type Code
• type Options
• type Result
  • func Run(ctx context.Context, service Service, interrupts <-chan struct{}, ...) Result
  • func (r Result) Code() string
  • func (r Result) Err() error
  • func (r Result) ExitCode() int
• type Service

Functions

func Fail

func Fail(code Code, safeMessage string, cause error) error

Fail classifies a host failure without exposing its original cause in Error.

func WriteError

func WriteError(w io.Writer, result Result) error

WriteError emits one JSON error line for a non-successful host result.

Types

type Code

type Code string

Code identifies the host lifecycle phase that failed.

const (
	CodeInternalError          Code = "internal_error"
	CodeConfigFailed           Code = "config_failed"
	CodeInitializationFailed   Code = "initialization_failed"
	CodeListenFailed           Code = "listen_failed"
	CodeServeFailed            Code = "serve_failed"
	CodeShutdownTimeout        Code = "shutdown_timeout"
	CodeShutdownCleanupTimeout Code = "shutdown_cleanup_timeout"
)

type Options

type Options struct {
	DrainTimeout   time.Duration
	CleanupTimeout time.Duration
}

Options bounds graceful draining and forced cleanup.

type Result

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

Result is the normalized host process outcome.

func Run

func Run(
	ctx context.Context,
	service Service,
	interrupts <-chan struct{},
	options Options,
) Result

Run starts service and synchronously drives it to one terminal Result.

func (Result) Code

func (r Result) Code() string

Code returns the normalized lifecycle failure code.

func (Result) Err

func (r Result) Err() error

Err returns the classified error. It can be inspected with errors.Is.

func (Result) ExitCode

func (r Result) ExitCode() int

ExitCode returns the process exit code selected by hostkit.

type Service

type Service interface {
	Start(context.Context) error
	Done() <-chan error
	Drain(context.Context) error
	ForceStop(context.Context) error
	Close(context.Context) error
}

Service is the lifecycle contract managed by Run.