Help us shape the future of Go! Take the 2026 Go Developer Survey

service

package
v0.15.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 26, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package service implements the gemaal ConnectRPC API — the six RPCs of proto/gemaal/v1 over the housekeeping engine.

Faces: Plan and Sweep are the janitor, ListTenants the console, Checkout and Extend the tenant-lifetime face, Resolve the identity authority. Mutations authenticate through pkg/authn (TokenReview for workloads, the gateway-forwarded JWT for humans) and authorize in authz.go; reads are open — the deployment's gateway and network policy bound who can reach them at all.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Authenticator added in v0.3.0 

type Authenticator interface {
	Authenticate(ctx context.Context, authorization string) (authn.Identity, error)
}

Authenticator resolves an Authorization header to an identity. *authn.Authenticator satisfies it; tests inject fakes.

type Deps added in v0.3.0 

type Deps struct {
	Config  *config.Config
	Logger  *slog.Logger
	Keeper  Housekeeper
	Auth    Authenticator
	History *engine.History
	// Version is the running build's identity, for the console footer.
	Version string
	// Now is the clock; time.Now when nil.
	Now func() time.Time
}

Deps wires a Service.

type Housekeeper added in v0.3.0 

type Housekeeper interface {
	View(ctx context.Context) (*engine.View, error)
	Plan(ctx context.Context, narrow engine.Narrow) (*engine.Plan, error)
	Apply(ctx context.Context, plan *engine.Plan, confirm bool, source string) (*engine.SweepRecord, error)
	StampKeepUntil(ctx context.Context, tenant engine.Tenant, until time.Time) error
	Decommission(ctx context.Context, namespace, release string, confirm bool) (*engine.SweepRecord, error)
}

Housekeeper is the engine surface the RPCs drive. *engine.Engine satisfies it; tests inject fakes.

type Service 

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

Service serves the gemaal.v1.GemaalService API.

func New 

func New(deps Deps) *Service

New wires a Service.

func (*Service) Checkout 

func (s *Service) Checkout(
	ctx context.Context,
	req *connect.Request[gemaalv1.CheckoutRequest],
) (*connect.Response[gemaalv1.CheckoutResponse], error)

Checkout claims a tenant slot for the caller: keep-until = now + duration (bounded by hold.max).

func (*Service) Decommission added in v0.8.0 

func (s *Service) Decommission(
	ctx context.Context,
	req *connect.Request[gemaalv1.DecommissionRequest],
) (*connect.Response[gemaalv1.DecommissionResponse], error)

Decommission uninstalls one tenant's release ring now. Same authorization as Checkout — this is a namespace owner ending their own tenant, the server-side twin of `gemaalctl uninstall`. The tenant's keep-until does not hold it; the server's dry-run wins.

func (*Service) Extend 

func (s *Service) Extend(
	ctx context.Context,
	req *connect.Request[gemaalv1.ExtendRequest],
) (*connect.Response[gemaalv1.ExtendResponse], error)

Extend pushes a tenant's keep-until forward — never backwards.

func (*Service) GetMe added in v0.15.0 

func (s *Service) GetMe(
	ctx context.Context,
	req *connect.Request[gemaalv1.GetMeRequest],
) (*connect.Response[gemaalv1.GetMeResponse], error)

GetMe returns the authenticated caller, so the console header can show who is signed in and whether operator affordances apply.

func (*Service) GetVersion added in v0.15.0 

func (s *Service) GetVersion(
	_ context.Context,
	_ *connect.Request[gemaalv1.GetVersionRequest],
) (*connect.Response[gemaalv1.GetVersionResponse], error)

GetVersion returns the running build's identity, for the console footer.

func (*Service) Handler 

func (s *Service) Handler() (string, http.Handler)

Handler returns the mount path and HTTP handler for the ConnectRPC API.

func (*Service) History added in v0.3.0 

func (s *Service) History(
	ctx context.Context,
	req *connect.Request[gemaalv1.HistoryRequest],
) (*connect.Response[gemaalv1.HistoryResponse], error)

History returns the sweep audit records for the console's Sweeps view. Read-only and derived from state the panel already showed to every authenticated viewer, so it authenticates but does not authorize.

func (*Service) ListTenants 

func (s *Service) ListTenants(
	ctx context.Context,
	req *connect.Request[gemaalv1.ListTenantsRequest],
) (*connect.Response[gemaalv1.ListTenantsResponse], error)

ListTenants enumerates the watched installations with ledger state and the action the loop would take next.

func (*Service) Plan 

func (s *Service) Plan(
	ctx context.Context,
	req *connect.Request[gemaalv1.PlanRequest],
) (*connect.Response[gemaalv1.PlanResponse], error)

Plan computes what housekeeping would do right now. No side effects, no authentication: the plan is the console's honesty, not a mutation.

func (*Service) Resolve 

func (s *Service) Resolve(
	ctx context.Context,
	req *connect.Request[gemaalv1.ResolveRequest],
) (*connect.Response[gemaalv1.ResolveResponse], error)

Resolve maps an email to its slug and standing namespace — the resolution authority, from the deployer-rendered map.

func (*Service) Sweep 

func (s *Service) Sweep(
	ctx context.Context,
	req *connect.Request[gemaalv1.SweepRequest],
) (*connect.Response[gemaalv1.SweepResponse], error)

Sweep executes the current plan, subject to the server's dry-run setting — a dry-run server reports and deletes nothing, whatever the request says.

func (*Service) SweepHistory added in v0.15.0 

func (s *Service) SweepHistory() *engine.History

SweepHistory exposes the raw sweep records (the History RPC serves the console's typed view of the same data).

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.