module

package
v0.0.30 Latest Latest
Warning

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

 Go to latest Published: Nov 12, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package module defines the versioned compile-time API Module contract for Sirius API extension (ADR-004).

go-api owns the contract, registry lifecycle, and Community ordering helper. Consuming API binaries (sirius-api Community builds and private Pro overlays) perform compile-time composition by constructing Modules and calling Register / RegisterCommunity / Mount. There is no runtime plugin loading. Licensing/entitlements are not implemented here; the capability middleware hook defaults to allow/no-op for Community.

Index

Constants

View Source 
const (
	IDHost                    = "community.host"
	IDApp                     = "community.app"
	IDVulnerability           = "community.vulnerability"
	IDTemplate                = "community.template"
	IDScript                  = "community.script"
	IDAgentTemplateRepository = "community.agent_template_repository"
	IDAgentTemplate           = "community.agent_template"
	IDEvent                   = "community.event"
	IDSnapshot                = "community.snapshot"
	IDStatistics              = "community.statistics"
	IDScan                    = "community.scan"
	IDAPIKey                  = "community.apikey"
)

Community module IDs document the historical sirius-api RouteSetter wiring order from main.go. Consuming API binaries should keep these IDs stable when adapting existing setters.

View Source 
const CommunityModuleVersion = "1.0.0"

CommunityModuleVersion is the default version stamped on Community adapters.

View Source 
const ContractVersion = "v1"

ContractVersion is the semantic version of this Module contract surface.

Variables

This section is empty.

Functions

func CapabilityMiddleware 

func CapabilityMiddleware(checker CapabilityChecker, capability string) fiber.Handler

CapabilityMiddleware returns Fiber middleware that rejects requests when the checker denies the required capability. A nil checker defaults to AllowAllChecker.

This task only provides the hook point; licensing/entitlements are out of scope.

func CommunityModuleIDs 

func CommunityModuleIDs() []string

CommunityModuleIDs returns a defensive copy of the canonical Community module ID list in registration order.

func RegisterCommunity 

func RegisterCommunity(reg *Registry, core CommunityCore) error

RegisterCommunity prevalidates the complete ordered Community module set and registers it atomically via Registry.RegisterAll. On any invalid, missing, typed-nil, ID-mismatched, or duplicate input the registry is left unchanged.

Callers may Register additional modules afterward (for tests or Pro modules composed by the API binary) until Mount succeeds.

func RouteInventory 

func RouteInventory(app *fiber.App) []string

RouteInventory returns METHOD\tPATH lines for routes on app.

Behavior:

  • Preserves Fiber stack order from GetRoutes(true) (per-method registration order). This keeps static-vs-parameter precedence visible within a method.
  • Preserves duplicates: consecutive identical registrations that Fiber merges into one route with N handlers emit N lines; distinct stack entries each emit at least one line.
  • Includes legitimate declared methods, including CONNECT and TRACE.
  • Omits only Fiber-generated HEAD mirrors: Fiber's Get/Group.Get always registers HEAD before GET for the same path/handlers. A HEAD entry is omitted when a GET exists for the same path. Explicit HEAD-only routes (no GET for that path) are kept.

func SetupRoutes 

func SetupRoutes(app *fiber.App, setters ...RouteSetter) error

SetupRoutes preserves the historical RouteSetter batch registration helper. Nil and typed-nil setters are rejected before any mutation.

Types

type AllowAllChecker 

type AllowAllChecker struct{}

AllowAllChecker grants every capability. This is the Community default.

func (AllowAllChecker) Has 

func (AllowAllChecker) Has(string) bool

Has always returns true.

type Base 

type Base struct {
	ModuleID      string
	ModuleVersion string
	Capabilities  []string
}

Base provides no-op defaults for optional Module methods so adapters stay small.

func (Base) Health 

func (b Base) Health(context.Context) HealthStatus

Health reports ok by default.

func (Base) ID 

func (b Base) ID() string

ID returns the module identifier.

func (Base) RegisterEventHandlers 

func (b Base) RegisterEventHandlers(EventRegistrar) error

RegisterEventHandlers is a no-op default.

func (Base) RegisterJobs 

func (b Base) RegisterJobs(JobRegistrar) error

RegisterJobs is a no-op default.

func (Base) RequiredCapabilities 

func (b Base) RequiredCapabilities() []string

RequiredCapabilities returns declared capability requirements (may be empty).

func (Base) Version 

func (b Base) Version() string

Version returns the module version string.

type CapabilityChecker 

type CapabilityChecker interface {
	Has(capability string) bool
}

CapabilityChecker is the entitlement hook point for future licensing. Community defaults to AllowAllChecker (always allow / no-op enforcement).

type CommunityCore 

type CommunityCore struct {
	Host                    Module
	App                     Module
	Vulnerability           Module
	Template                Module
	Script                  Module
	AgentTemplateRepository Module
	AgentTemplate           Module
	Event                   Module
	Snapshot                Module
	Statistics              Module
	Scan                    Module
	APIKey                  Module
}

CommunityCore holds the Community API modules supplied by the consuming API binary. Handlers remain in sirius-api (or a private Pro overlay); this helper only validates order and registers Modules atomically.

Compile-time composition belongs in the consuming API (Community wiring or a private Pro overlay). go-api provides the contract and this ordering helper; it is not a file that Pro "replaces" inside the SDK checkout.

type EventHandler 

type EventHandler func(ctx context.Context, payload []byte) error

EventHandler processes a typed event payload.

type EventRegistrar 

type EventRegistrar interface {
	RegisterHandler(eventType string, handler EventHandler) error
}

EventRegistrar collects event handlers at startup. Community may use a no-op.

type HealthStatus 

type HealthStatus struct {
	Status  string            `json:"status"` // "ok", "degraded", or "error"
	Message string            `json:"message,omitempty"`
	Details map[string]string `json:"details,omitempty"`
}

HealthStatus is a lightweight module health report.

type JobFunc 

type JobFunc func(ctx context.Context) error

JobFunc is a named background job entry point registered by a Module.

type JobRegistrar 

type JobRegistrar interface {
	RegisterJob(name string, job JobFunc) error
}

JobRegistrar collects background jobs at startup. Community may use a no-op.

type Module 

type Module interface {
	ID() string
	Version() string
	RegisterRoutes(app *fiber.App) error
	RegisterJobs(reg JobRegistrar) error
	RegisterEventHandlers(reg EventRegistrar) error
	RequiredCapabilities() []string
	Health(ctx context.Context) HealthStatus
}

Module is the versioned compile-time extension contract for API surfaces. Implementations must be deterministic and free of runtime plugin loading.

func AdaptRouteSetter 

func AdaptRouteSetter(id, version string, setter RouteSetter) (Module, error)

AdaptRouteSetter wraps a legacy RouteSetter as a Module. Nil and typed-nil setters are rejected; an empty module is never returned.

type NoopEventRegistrar 

type NoopEventRegistrar struct{}

NoopEventRegistrar discards event handler registrations.

func (NoopEventRegistrar) RegisterHandler 

func (NoopEventRegistrar) RegisterHandler(string, EventHandler) error

RegisterHandler implements EventRegistrar.

type NoopJobRegistrar 

type NoopJobRegistrar struct{}

NoopJobRegistrar discards job registrations.

func (NoopJobRegistrar) RegisterJob 

func (NoopJobRegistrar) RegisterJob(string, JobFunc) error

RegisterJob implements JobRegistrar.

type Registry 

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

Registry holds compile-time registered Modules and mounts them onto an app.

Lifecycle: Register/RegisterAll are allowed only while open; Mount may succeed exactly once. Module callbacks run without holding the registry lock.

func NewRegistry 

func NewRegistry() *Registry

NewRegistry returns an empty module registry.

func (*Registry) Health 

func (r *Registry) Health(ctx context.Context) map[string]HealthStatus

Health aggregates per-module health reports keyed by module ID.

func (*Registry) ModuleIDs 

func (r *Registry) ModuleIDs() []string

ModuleIDs returns registered module IDs in registration order.

func (*Registry) Modules 

func (r *Registry) Modules() []Module

Modules returns registered modules in registration order.

func (*Registry) Mount 

func (r *Registry) Mount(app *fiber.App, jobs JobRegistrar, events EventRegistrar) error

Mount registers routes, jobs, and event handlers for all modules. jobs/events may be nil (treated as no-op registrars).

Exactly one successful Mount is permitted. On callback failure the registry returns to open (lifecycle-consistent) so registration may continue; the Fiber app may already be partially mutated and is not rolled back.

func (*Registry) Mounted 

func (r *Registry) Mounted() bool

Mounted reports whether Mount has completed successfully.

func (*Registry) Register 

func (r *Registry) Register(m Module) error

Register adds a module. Duplicate IDs and nil/typed-nil modules are rejected. Registration is refused after Mount starts or completes.

func (*Registry) RegisterAll 

func (r *Registry) RegisterAll(modules ...Module) error

RegisterAll validates the entire batch, then appends all modules or none.

type RouteSetter 

type RouteSetter interface {
	SetupRoutes(app *fiber.App)
}

RouteSetter is the legacy Fiber route registration contract used by sirius-api. New code should implement Module; AdaptRouteSetter bridges existing setters.

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.