extension

Documentation

Overview

Package extension provides a Forge extension adapter for the ctrlplane. It enables mounting CtrlPlane into a Forge application with automatic DI resolution, route registration, and lifecycle management.

Index

• Constants
• type Config
  • func DefaultConfig() Config
  • func (c Config) ToCtrlPlaneConfig() ctrlplane.Config
• type ExtOption
  • func WithAuthProvider(p auth.Provider) ExtOption
  • func WithBasePath(path string) ExtOption
  • func WithConfig(cfg Config) ExtOption
  • func WithDisableMigrate() ExtOption
  • func WithDisableRoutes() ExtOption
  • func WithExtension(x plugin.Extension) ExtOption
  • func WithProvider(name string, p provider.Provider) ExtOption
  • func WithRequireConfig(require bool) ExtOption
  • func WithStore(opt app.Option) ExtOption
• type Extension
  • func New(opts ...ExtOption) *Extension
  • func (e *Extension) API() *api.API
  • func (e *Extension) CtrlPlane() *app.CtrlPlane
  • func (e *Extension) Handler() http.Handler
  • func (e *Extension) Health(ctx context.Context) error
  • func (e *Extension) Init(fapp forge.App) error
  • func (e *Extension) Register(fapp forge.App) error
  • func (e *Extension) RegisterRoutes(router forge.Router)
  • func (e *Extension) Start(ctx context.Context) error
  • func (e *Extension) Stop(ctx context.Context) error

Constants

const ExtensionDescription = "CtrlPlane control plane for managing cloud infrastructure and deployments"

const ExtensionName = "ctrlplane"

ExtensionName is the name registered with Forge.

const ExtensionVersion = "0.1.0"

Types

type Config

type Config struct {
	// Config embeds the core ctrlplane configuration.
	ctrlplane.Config `json:",inline" mapstructure:",squash" yaml:",inline"`

	// BasePath is the URL prefix for all ctrlplane routes.
	BasePath string `json:"base_path" mapstructure:"base_path" yaml:"base_path"`

	// AuthProvider is an explicitly configured auth provider.
	// If nil, the extension auto-discovers from Forge's DI container.
	AuthProvider auth.Provider `json:"-" yaml:"-"`

	// DisableRoutes disables the registration of routes.
	DisableRoutes bool `json:"disable_routes" mapstructure:"disable_routes" yaml:"disable_routes"`

	// DisableMigrate disables automatic database migration on Register.
	DisableMigrate bool `json:"disable_migrate" mapstructure:"disable_migrate" yaml:"disable_migrate"`

	// RequireConfig requires config to be present in YAML files.
	// If true and no config is found, Register returns an error.
	RequireConfig bool `json:"-" yaml:"-"`
}

Config holds configuration for the CtrlPlane Forge extension. Fields can be set programmatically via ExtOption functions or loaded from YAML configuration files (under "extensions.ctrlplane" or "ctrlplane" keys).

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns a Config with sensible defaults.

func (Config) ToCtrlPlaneConfig

func (c Config) ToCtrlPlaneConfig() ctrlplane.Config

ToCtrlPlaneConfig returns the embedded ctrlplane config.

type ExtOption

type ExtOption func(*Extension)

ExtOption configures the CtrlPlane Forge extension.

func WithAuthProvider

func WithAuthProvider(p auth.Provider) ExtOption

WithAuthProvider sets an explicit auth provider instead of auto-discovery.

func WithBasePath

func WithBasePath(path string) ExtOption

WithBasePath sets the URL prefix for all ctrlplane routes.

func WithConfig

func WithConfig(cfg Config) ExtOption

WithConfig sets the extension configuration directly.

func WithDisableMigrate

func WithDisableMigrate() ExtOption

WithDisableMigrate disables automatic database migration on Register.

func WithDisableRoutes

func WithDisableRoutes() ExtOption

WithDisableRoutes disables automatic route registration.

func WithExtension

func WithExtension(x plugin.Extension) ExtOption

WithExtension registers a plugin extension (lifecycle hooks).

func WithProvider

func WithProvider(name string, p provider.Provider) ExtOption

WithProvider registers a cloud/orchestrator provider.

func WithRequireConfig

func WithRequireConfig(require bool) ExtOption

WithRequireConfig requires config to be present in YAML files.

func WithStore

func WithStore(opt app.Option) ExtOption

WithStore sets the store via an app option.

type Extension

type Extension struct {
	*forge.BaseExtension
	// contains filtered or unexported fields
}

Extension adapts CtrlPlane as a Forge extension. It implements the forge.Extension interface when used with Forge.

func New

func New(opts ...ExtOption) *Extension

New creates a CtrlPlane Forge extension with the given options.

func (*Extension) API

func (e *Extension) API() *api.API

API returns the API handler.

func (*Extension) CtrlPlane

func (e *Extension) CtrlPlane() *app.CtrlPlane

CtrlPlane returns the underlying CtrlPlane instance. This is nil until Init is called.

func (*Extension) Handler

func (e *Extension) Handler() http.Handler

Handler returns the HTTP handler for all API routes. This is a convenience method for standalone use.

func (*Extension) Health

func (e *Extension) Health(ctx context.Context) error

Health implements forge.Extension.

func (*Extension) Init

func (e *Extension) Init(fapp forge.App) error

Init initializes the extension. In a Forge environment, this is called during app setup. For standalone use, call it manually.

func (*Extension) Register

func (e *Extension) Register(fapp forge.App) error

Register implements forge.Extension.

func (*Extension) RegisterRoutes

func (e *Extension) RegisterRoutes(router forge.Router)

RegisterRoutes registers all ctrlplane API routes into a Forge router with full OpenAPI metadata. Use this for Forge extension integration where the parent app owns the router.

func (*Extension) Start

func (e *Extension) Start(ctx context.Context) error

Start begins background workers.

func (*Extension) Stop

func (e *Extension) Stop(ctx context.Context) error

Stop gracefully shuts down.