Skip to content

Modern Docker Management, Designed for Everyone

9.8 KB
Raw Blame
// Package francis owns the embedded Francis host lifecycle.
package francis

import (
	"context"
	"crypto/hkdf"
	"crypto/sha256"
	"database/sql"
	"errors"
	"fmt"
	"log/slog"
	"net"
	"os"
	"slices"
	"strconv"
	"strings"
	"sync"
	"syscall"
	"time"

	"github.com/italypaleale/francis/actor"
	"github.com/italypaleale/francis/builtin/workflow"
	"github.com/italypaleale/francis/components"
	"github.com/italypaleale/francis/host/local"
	"github.com/libtnb/sqlite"
	"gorm.io/driver/postgres"
	"gorm.io/gorm"
	"gorm.io/gorm/logger"
)

// TablePrefix namespaces the Francis tables in their store.
const TablePrefix = "arcane_francis"

// Runtime starts one durable actor host and publishes its service after readiness.
// Services must wait for Ready before using Service, including during startup retries.
type Runtime struct {
	mu            sync.Mutex
	options       []local.HostOption
	registrations []registration
	workflows     []*workflow.Workflow
	service       *actor.Service
	ready         chan struct{}
	done          chan struct{}
	cancel        context.CancelFunc
	started       bool
	runError      error
	address       string
	storeURL      string
	store         *gorm.DB
	actorNames    sync.Map
}

type registration struct {
	actorType string
	factory   actor.Factory
	options   []local.RegisterActorOption
}

func New(databaseURL, encryptionKey, instanceID, port string, options ...local.HostOption) (*Runtime, error) {
	if port == "" {
		port = "3551"
	}
	portNumber, err := strconv.Atoi(port)
	if err != nil || portNumber < 1 || portNumber > 65535 {
		return nil, errors.New("ACTOR_PORT must be between 1 and 65535")
	}
	storeURL, err := StoreURL(databaseURL)
	if err != nil {
		return nil, err
	}
	// The QUIC peer server only listens on loopback, where a kernel-capped UDP buffer costs nothing, so
	// quic-go's buffer-size warning is noise unless the operator opted back in.
	if _, set := os.LookupEnv("QUIC_GO_DISABLE_RECEIVE_BUFFER_WARNING"); !set {
		// Setenv only fails for keys containing '=' or NUL, which this constant key cannot.
		_ = os.Setenv("QUIC_GO_DISABLE_RECEIVE_BUFFER_WARNING", "true")
	}
	address := net.JoinHostPort("127.0.0.1", port)
	runtime := &Runtime{
		service: &actor.Service{}, ready: make(chan struct{}), done: make(chan struct{}), address: address, storeURL: storeURL,
		options: []local.HostOption{
			local.WithAddress(address), providerOption(storeURL),
			local.WithMaxHosts(1), local.WithHostHealthCheckDeadline(150 * time.Second),
			local.WithShutdownGracePeriod(10 * time.Second), local.WithAlarmsPollInterval(10 * time.Second),
			local.WithAlarmsFetchAheadInterval(30 * time.Second), local.WithAlarmsLeaseDuration(180 * time.Second),
		},
	}
	runtime.options = append(runtime.options, local.WithLogger(slog.New(&actorLogHandler{
		Handler: slog.Default().With("scope", "francis.arcane.internal").Handler(),
		names:   &runtime.actorNames,
	})))
	if encryptionKey != "" && instanceID != "" {
		if configureIdentityErr := runtime.ConfigureIdentity(encryptionKey, instanceID); configureIdentityErr != nil {
			return nil, configureIdentityErr
		}
	}
	runtime.options = append(runtime.options, options...)
	return runtime, nil
}

// ConfigureIdentity binds the final persisted identity before Start.
func (r *Runtime) ConfigureIdentity(encryptionKey, instanceID string) error {
	r.mu.Lock()
	defer r.mu.Unlock()
	if r.started {
		return errors.New("actor identity cannot change after startup")
	}
	if encryptionKey == "" || instanceID == "" {
		return errors.New("actor host requires the encryption key and instance ID")
	}
	psk, err := hkdf.Key(sha256.New, []byte(encryptionKey), nil, "arcane/actors-psk/"+instanceID, 32)
	if err != nil {
		return fmt.Errorf("derive actor authentication key: %w", err)
	}
	r.options = append(r.options, local.WithRuntimePSKs(psk))
	return nil
}

func (r *Runtime) Service() *actor.Service { return r.service }
func (r *Runtime) Ready() <-chan struct{}  { return r.ready }
func (r *Runtime) Done() <-chan struct{}   { return r.done }

// Store lazily opens a small pool on Francis storage for diagnostics and backups.
func (r *Runtime) Store() (*gorm.DB, error) {
	r.mu.Lock()
	defer r.mu.Unlock()
	if r.store != nil {
		return r.store, nil
	}
	dialector := postgres.Open(r.storeURL)
	if strings.HasPrefix(r.storeURL, "file:") {
		dialector = sqlite.Open(r.storeURL)
	}
	store, err := gorm.Open(dialector, &gorm.Config{Logger: logger.Discard})
	if err != nil {
		return nil, fmt.Errorf("open actor storage: %w", err)
	}
	sqlDB, err := store.DB()
	if err != nil {
		return nil, fmt.Errorf("open actor storage: %w", err)
	}
	sqlDB.SetMaxOpenConns(2)
	r.store = store
	return store, nil
}

func (r *Runtime) RegisterActor(actorType string, factory actor.Factory, options ...local.RegisterActorOption) error {
	r.mu.Lock()
	defer r.mu.Unlock()
	if r.started {
		return errors.New("actor factories must be registered before startup")
	}
	for _, registration := range r.registrations {
		if registration.actorType == actorType {
			return fmt.Errorf("actor type %q is already registered", actorType)
		}
	}
	r.registrations = append(r.registrations, registration{actorType: actorType, factory: factory, options: append([]local.RegisterActorOption(nil), options...)})
	return nil
}

// RegisterWorkflow adds a Francis workflow, registered on every host attempt.
func (r *Runtime) RegisterWorkflow(wf *workflow.Workflow) error {
	r.mu.Lock()
	defer r.mu.Unlock()
	if r.started {
		return errors.New("workflows must be registered before startup")
	}
	if slices.ContainsFunc(r.workflows, func(existing *workflow.Workflow) bool { return existing.Name() == wf.Name() }) {
		return fmt.Errorf("workflow %q is already registered", wf.Name())
	}
	r.workflows = append(r.workflows, wf)
	return nil
}

// Start waits for host registration. appCtx owns the running host; ctx only
// limits startup. onFailure must cancel the application without blocking.
func (r *Runtime) Start(ctx, appCtx context.Context, onFailure func(error)) error {
	r.mu.Lock()
	if r.started {
		r.mu.Unlock()
		return errors.New("actor host already started")
	}
	r.started = true
	runCtx, cancel := context.WithCancel(appCtx)
	r.cancel = cancel
	r.mu.Unlock()
	var listenerConfig net.ListenConfig
	listener, err := listenerConfig.ListenPacket(ctx, "udp", r.address)
	if err != nil {
		cancel()
		err = fmt.Errorf("bind actor loopback UDP listener: %w", err)
		r.finish(err)
		return err
	}
	if err = listener.Close(); err != nil {
		cancel()
		r.finish(err)
		return err
	}
	startupCtx, startupCancel := context.WithTimeout(ctx, 120*time.Second)
	defer startupCancel()
	bindRetries := 0

	for {
		host, errCh, runHostErr := r.runHost(runCtx)
		if runHostErr != nil {
			cancel()
			r.finish(runHostErr)
			return runHostErr
		}
		select {
		case <-host.Ready():
			select {
			case runHostErr = <-errCh:
			default:
				r.publishReady(runCtx, host, errCh, onFailure)
				return nil
			}
		case runHostErr = <-errCh:
		case <-startupCtx.Done():
			cancel()
			r.finish(<-errCh)
			return startupCtx.Err()
		}
		if runHostErr == nil {
			runHostErr = errors.New("actor host stopped during startup")
		}
		switch {
		case errors.Is(runHostErr, syscall.EADDRINUSE) && bindRetries < 3:
			bindRetries++
			slog.WarnContext(ctx, "Retrying actor host after a UDP port conflict", "error", runHostErr, "retry", bindRetries)
		case errors.Is(runHostErr, components.ErrClusterFull), errors.Is(runHostErr, components.ErrHostAlreadyRegistered):
			slog.WarnContext(ctx, "Waiting for the previous actor host registration to expire", "error", runHostErr)
		default:
			cancel()
			r.finish(runHostErr)
			return runHostErr
		}
		timer := time.NewTimer(time.Second)
		select {
		case <-timer.C:
		case <-runCtx.Done():
			timer.Stop()
			r.finish(runCtx.Err())
			return runCtx.Err()
		case <-startupCtx.Done():
			timer.Stop()
			cancel()
			runHostErr = fmt.Errorf("actor host startup timed out: %w", errors.Join(startupCtx.Err(), runHostErr))
			r.finish(runHostErr)
			return runHostErr
		}
	}
}

func (r *Runtime) runHost(ctx context.Context) (*local.Host, chan error, error) {
	host, err := local.NewHost(r.options...)
	if err != nil {
		return nil, nil, err
	}
	var registerErr error
	for _, registration := range r.registrations {
		if registerErr = host.RegisterActor(registration.actorType, registration.factory, registration.options...); registerErr != nil {
			break
		}
	}
	for _, wf := range r.workflows {
		if registerErr != nil {
			break
		}
		registerErr = host.RegisterBuiltInActor(wf)
	}
	if registerErr != nil {
		// Running a canceled host closes its provider-owned connections.
		cleanupCtx, cancel := context.WithCancel(ctx)
		cancel()
		if cleanupErr := host.Run(cleanupCtx); cleanupErr != nil {
			return nil, nil, errors.Join(registerErr, fmt.Errorf("clean up unregistered actor host: %w", cleanupErr))
		}
		return nil, nil, registerErr
	}
	localErrors := make(chan error, 1)
	go func() { localErrors <- host.Run(ctx) }()
	return host, localErrors, nil
}

func (r *Runtime) publishReady(ctx context.Context, host *local.Host, runErrors <-chan error, onFailure func(error)) {
	*r.service = *host.Service()
	close(r.ready)
	go func() {
		err := <-runErrors
		if ctx.Err() != nil || onFailure == nil {
			r.finish(err)
			return
		}
		// onFailure reports the error, so Stop must not return it again.
		r.finish(nil)
		if err == nil {
			err = errors.New("actor host stopped unexpectedly")
		}
		onFailure(err)
	}()
}

func (r *Runtime) Stop(ctx context.Context) error {
	r.mu.Lock()
	var err error
	if r.store != nil {
		var sqlDB *sql.DB
		if sqlDB, err = r.store.DB(); err == nil {
			err = sqlDB.Close()
		}
		r.store = nil
	}
	if !r.started {
		r.mu.Unlock()
		return err
	}
	r.mu.Unlock()
	r.cancel()
	select {
	case <-r.done:
		r.mu.Lock()
		defer r.mu.Unlock()
		return errors.Join(r.runError, err)
	case <-ctx.Done():
		return errors.Join(ctx.Err(), err)
	}
}

func (r *Runtime) finish(err error) {
	r.mu.Lock()
	defer r.mu.Unlock()
	r.runError = err
	close(r.done)
}