Skip to content

Infisical is the open-source platform for securing secrets, certificates, access, and AI Agents.

6.3 KB
Raw Blame
package infra

import (
	"context"
	"fmt"
	"sort"
	"strings"
)

// ModuleKey identifies a module for lookup. A module that can appear more than once
// qualifies its key with the instance name, so postgres.Module(postgres.Named(
// "rotation")) is "postgres:rotation" and does not collide with "postgres".
type ModuleKey string

// Module is a container the harness can start. Implementations live in
// infra/<name> and are about thirty lines each, because Deps.Run does the work.
type Module interface {
	Key() ModuleKey

	// Name is the identity-bearing part of the container name. The harness supplies
	// scope and scope id; a module supplies its own module name, instance, and a
	// fingerprint if and only if staleness would be silent for it.
	Name() NameParts

	// Requires lists modules this one cannot start without. Validated before
	// anything starts, so a missing dependency fails immediately rather than as a
	// connection timeout ninety seconds later.
	Requires() []ModuleKey

	Start(context.Context, Deps) (Handle, error)
}

// Handle is a started container.
type Handle interface {
	Endpoint(Mode) Endpoint
	Stop(context.Context) error
}

// Deps is what a module sees during Start: every module that has already started,
// plus the network they share.
type Deps struct {
	handles   map[ModuleKey]Handle
	network   string
	workspace string
	name      NameParts
	runner    Runner
	log       Logger
}

func (d Deps) Network() string { return d.network }

// ContainerName is the name this module's container will get. A module needs it to
// build a URL pointing at itself, which Infisical does for SITE_URL.
func (d Deps) ContainerName() string { return ContainerName(d.name) }

// Run starts this module's container. Name, alias and labels are filled in from the
// resolved scope, so a module never computes its own identity and cannot get the
// naming convention subtly wrong.
func (d Deps) Run(ctx context.Context, spec ContainerSpec) (Container, error) {
	if spec.Name == "" {
		spec.Name = ContainerName(d.name)
	}
	if spec.Alias == "" {
		spec.Alias = spec.Name
	}
	if spec.Labels == nil {
		spec.Labels = Labels(d.name, d.workspace)
	}
	if spec.Network == "" {
		spec.Network = d.network
	}
	return d.runner.Run(ctx, spec)
}

// NewDeps builds the Deps handed to one module's Start.
func NewDeps(handles map[ModuleKey]Handle, network, workspace string, name NameParts, r Runner, log Logger) Deps {
	if log == nil {
		log = NewLogger()
	}
	return Deps{handles: handles, network: network, workspace: workspace, name: name, runner: r, log: log}
}

func (d Deps) Log() Logger { return d.log }

// Get returns a typed handle, or false when the module was not declared.
//
// A generic method rather than a package function, which Go 1.27 allows. Modules
// still wrap it (fakenet.MustFrom, postgres.MustFrom) so call sites read as prose.
func (d Deps) Get[H Handle](k ModuleKey) (H, bool) {
	h, ok := d.handles[k]
	if !ok {
		var zero H
		return zero, false
	}
	typed, ok := h.(H)
	return typed, ok
}

// Plan is a validated, ordered set of modules ready to start.
type Plan struct {
	modules []Module
	scopes  map[ModuleKey]Scope
}

func (p Plan) Modules() []Module         { return p.modules }
func (p Plan) Scope(k ModuleKey) Scope   { return p.scopes[k] }
func (p Plan) Declared(k ModuleKey) bool { _, ok := p.scopes[k]; return ok }

// Resolve validates a module set and returns it in dependency order.
//
// Everything here runs before a single container starts, so every failure below is
// instant and names the fix.
func Resolve(modules []Module, scopes map[ModuleKey]Scope) (Plan, error) {
	byKey := make(map[ModuleKey]Module, len(modules))
	for _, m := range modules {
		if _, dup := byKey[m.Key()]; dup {
			return Plan{}, fmt.Errorf("infra: module %q declared twice; use Named() to run a second instance", m.Key())
		}
		byKey[m.Key()] = m
	}

	for _, m := range modules {
		for _, dep := range m.Requires() {
			if _, ok := byKey[dep]; !ok {
				return Plan{}, fmt.Errorf("infra: %s requires %s, which was not declared", m.Key(), dep)
			}
		}
		if err := checkLifetimes(m, scopes); err != nil {
			return Plan{}, err
		}
	}

	ordered, err := topoSort(modules, byKey)
	if err != nil {
		return Plan{}, err
	}
	return Plan{modules: ordered, scopes: scopes}, nil
}

// checkLifetimes rejects a module that depends on something shorter lived than
// itself. A Shared Infisical takes fakenet's address and CA when its container is
// created, so if fakenet were Package-scoped it would vanish when that package
// finished and break every other package still using the instance.
func checkLifetimes(m Module, scopes map[ModuleKey]Scope) error {
	mine, ok := scopes[m.Key()]
	if !ok {
		return fmt.Errorf("infra: no scope declared for %s", m.Key())
	}
	for _, dep := range m.Requires() {
		theirs := scopes[dep]
		if theirs.LongerLivedThan(mine) || theirs == mine {
			continue
		}
		return fmt.Errorf(
			"infra: %s is %s-scoped but depends on %s which is %s-scoped.\n"+
				"A container reads its configuration once at start, so it cannot point at something that dies first.\n"+
				"Either widen %s to %s, or narrow %s to %s",
			m.Key(), mine, dep, theirs, dep, mine, m.Key(), theirs)
	}
	return nil
}

func topoSort(modules []Module, byKey map[ModuleKey]Module) ([]Module, error) {
	const (
		unvisited = iota
		inProgress
		done
	)
	state := make(map[ModuleKey]int, len(modules))
	out := make([]Module, 0, len(modules))
	var path []ModuleKey

	var visit func(m Module) error
	visit = func(m Module) error {
		switch state[m.Key()] {
		case done:
			return nil
		case inProgress:
			return fmt.Errorf("infra: dependency cycle: %s -> %s", joinKeys(path), m.Key())
		}
		state[m.Key()] = inProgress
		path = append(path, m.Key())

		deps := append([]ModuleKey{}, m.Requires()...)
		sort.Slice(deps, func(i, j int) bool { return deps[i] < deps[j] })
		for _, k := range deps {
			if dep, ok := byKey[k]; ok {
				if err := visit(dep); err != nil {
					return err
				}
			}
		}

		path = path[:len(path)-1]
		state[m.Key()] = done
		out = append(out, m)
		return nil
	}

	sorted := append([]Module{}, modules...)
	sort.Slice(sorted, func(i, j int) bool { return sorted[i].Key() < sorted[j].Key() })
	for _, m := range sorted {
		if err := visit(m); err != nil {
			return nil, err
		}
	}
	return out, nil
}

func joinKeys(ks []ModuleKey) string {
	s := make([]string, len(ks))
	for i, k := range ks {
		s[i] = string(k)
	}
	return strings.Join(s, " -> ")
}