pdk

type ChainPosition ¶

type ChainPosition int

ChainPosition selects where a plugin's middleware is spliced into the server's request chain. Only two positions are exposed on purpose: a plugin can wrap the whole request or run with the authenticated identity, without the platform's internal middleware order becoming part of the public contract. A plugin cannot insert middleware *between* platform steps (e.g. between auth and the scope enforcer).

const (
	// BeforePlatformChain is outermost: it runs before CORS and auth, on every
	// request, with NO authenticated identity in the context yet. Good for request
	// IDs, tracing, panic recovery, IP allow-lists. It cannot mark a request as
	// authenticated — the platform's auth always runs after it and is the only
	// thing that sets identity, so GO-AUTH-005 still holds.
	BeforePlatformChain ChainPosition = iota
	// AfterPlatformChain is innermost: it runs after auth, organization
	// resolution, and scope enforcement, just before routing. The authenticated
	// org and identity are in the context and can be read with
	// middleware.GetOrganizationFromRequest.
	// Good for per-tenant rate limiting, audit, or request enrichment — still
	// scoped by the org from context (GO-AUTH-005).
	AfterPlatformChain
)

type Deps ¶

type Deps struct {
	Gateways Gateways

	Config *config.Server
	Logger *slog.Logger
}

Deps gives an external plugin the platform's capabilities as interfaces grouped by area, using only public types. It never hands over repositories, DB handles, or concrete internal service types — the type system keeps model.* / repository.* from leaking out.

Capabilities are added here as external plugins need them. Each interface is satisfied by shape by the concrete internal service — the methods listed are exactly existing service methods that already speak public types — so exposing one is a plain assignment in the server (see StartPlatformAPIServer), with no adapter code. The assignment itself is the compile-time contract check: if a signature drifts, the server stops building.

type Gateways ¶

type Gateways interface {
	// RegisterGateway creates a gateway in an organization (Create).
	RegisterGateway(orgID string, id *string, displayName, description string, endpoints []string,
		isCritical bool, functionalityType, version, createdBy string, properties map[string]any) (*api.GatewayResponse, error)

	// GetGateway returns a single gateway by id within an organization (Read).
	GetGateway(gatewayID, orgID string) (*api.GatewayResponse, error)

	// UpdateGateway updates a gateway within an organization (Update).
	UpdateGateway(gatewayID, orgID, updatedBy string, req *api.GatewayResponse) (*api.GatewayResponse, error)

	// DeleteGateway removes a gateway within an organization (Delete).
	DeleteGateway(gatewayID, orgID, deletedBy string) error
}

Gateways exposes CRUD access to the platform's gateways, scoped by organization. Every method mirrors an existing GatewayService method verbatim and takes the organization id explicitly — handlers MUST pass the org resolved from the request context, never one from request input (GO-AUTH-005).

type Middleware ¶

type Middleware func(http.Handler) http.Handler

Middleware is a standard Go middleware — it wraps one handler with another.

type MiddlewareProvider ¶

type MiddlewareProvider interface {
	Middleware() []PositionedMiddleware
}

MiddlewareProvider is an OPTIONAL interface a Plugin may implement to contribute middleware to the request chain. Return an empty slice to add none. Within a position, middleware runs in plugin registration order.

type Plugin ¶

type Plugin interface {
	// Name returns a short identifier for the plugin (e.g. "api-cloud").
	Name() string

	// Init receives the platform capabilities (pdk.Deps). Called once at startup
	// before routes are registered; return an error to abort startup.
	Init(deps *Deps) error

	// RegisterRoutes mounts the plugin's HTTP routes on the shared mux. Only
	// called after Init has succeeded. Every route registered here is served
	// through the platform's authentication and scope chain.
	RegisterRoutes(mux *http.ServeMux)

	// OpenAPISpec returns the plugin's OpenAPI 3.x YAML bytes, merged into the
	// platform scope registry to enforce per-route scopes. It is mandatory:
	// returning empty bytes or bytes the registry loader rejects aborts startup.
	//
	// The merged registry is what the scope stage consults on each request, keyed
	// by the matched route pattern. Declare the scopes each route requires
	// (GO-AUTH-007).
	OpenAPISpec() []byte

	// Shutdown is called during graceful server shutdown.
	Shutdown(ctx context.Context) error
}

Plugin is the contract an external extension implements. Every method signature uses only public types, so a Plugin can live in a separate module without importing platform-api's internal/ packages.

type PositionedMiddleware ¶

type PositionedMiddleware struct {
	Position ChainPosition
	Wrap     Middleware
}

PositionedMiddleware pairs a middleware with the position it should occupy in the chain.