[Proposal] Two-tier plugin model: internal plugins + external PDK

[malinthaprasan]

1. Why we need this

Two very different kinds of code need to extend platform-api. We trust them differently, and — this is the important part — we owe them different promises about not breaking their code later:

1. Features we build inside this repo that aren't ready to ship yet (or are turned off for some other reason) but still need to be committed. Example: the eventgateway plugin (WebSub / WebBroker). This code lives in the repo, is compiled with it, and genuinely needs deep access to everything.

2. Extensions in a separate repo that import platform-api as a library. Example: api-cloud. These need a small, stable set of things to build against. If we let them reach into the repository layer (or raw internal service types), then every small refactor we do becomes a breaking change for them. Repository method signatures change often, and we don't want to freeze them.

The model we have today (one public Plugin type with a Deps that hands over raw repositories) treats both the same. It gives external code the same deep, unstable access that in-repo code gets. This proposal splits extension into two tiers, so the only code we promise to keep stable is a small, deliberate public surface.

2. The two tiers

	Internal plugin	External plugin (PDK)
Example	eventgateway	api-cloud
Where it lives	in this repo, behind a build tag	separate module / repo
What it's for	commit unfinished / turned-off features without shipping them	third-party or wrapper extensions
What it implements	internal/plugin.Plugin	pdk.Plugin (public)
What it gets (Deps)	everything — raw repos, services, DB, event hub	a small set — capability interfaces only
What it can import	any package, including internal/	only pdk + api (both public)
Do we promise to keep it stable?	No — refactor freely, it recompiles with the repo	Yes — this is the contract we version
How it's registered	builtinPlugins() (build tag)	platform.WithPlugin(...)

The rule of thumb: the only code we promise to keep stable is the external surface (pdk + api). Everything under it — service, repository, model — stays in internal/ and we can change it whenever we like. Internal plugins never count here, because they are rebuilt along with the repo.

3. The external surface: the pdk package

pdk ("Plugin Development Kit") is the one public package an external plugin builds against. It holds only interfaces, small value types, and helpers to read the request — no real logic. It imports only api (the public OpenAPI DTOs), config, and the standard library.

pdk/
  plugin.go     Plugin interface + Deps struct
  deps.go       capability interfaces (APIs, Gateways, Subscriptions, …)
  options.go    shared value types (ListOptions, …)
  request.go    request-context accessors (OrganizationFromRequest, …)

3.1 What an external plugin must implement

package pdk

type Plugin interface {
    Name() string
    Init(deps *Deps) error
    RegisterRoutes(mux *http.ServeMux)
    OpenAPISpec() []byte
    Shutdown(ctx context.Context) error
}

// Optional interfaces a Plugin may also implement:
type AuthSkipPathProvider interface { AuthSkipPaths() []string }
type MiddlewareProvider   interface { Middleware() []PositionedMiddleware } // see Section 5.2

3.2 Deps — capabilities, not repositories

pdk.Deps gives a plugin the platform's capabilities as interfaces grouped by area, and only in public types. It never hands over repositories, DB handles, or the concrete internal service types.

package pdk

type Deps struct {
    APIs          APIs
    Gateways      Gateways
    Subscriptions Subscriptions
    Applications  Applications
    Projects      Projects
    Organizations Organizations
    LLM           LLM
    MCP           MCP
    Deployments   Deployments
    Secrets       Secrets
    APIKeys       APIKeys
    // add more as external plugins need them

    Config *config.Server // or a public read-only subset
    Logger *slog.Logger
}

type ListOptions struct {
    Limit  int
    Offset int
    Search string
}

type APIs interface {
    CountAPIs(orgID string) (int, error)
    GetAPIByUUID(apiUUID, orgID string) (*api.RESTAPI, error)
    ListAPIs(orgID, projectHandle string, opts ListOptions) ([]api.RESTAPI, int, error)
}

type Gateways interface {
    // *service.GatewayService already matches this — its types are public.
    GetGateway(gatewayID, orgID string) (*api.GatewayResponse, error)
}
// Subscriptions, Applications, … the same way

4. How it works — a list of allowed methods, not a wrapper layer

The capability interfaces are not a hand-written pass-through layer — that would not scale to ~25 services and ~200 methods. Instead we lean on a Go feature: a type satisfies an interface just by having the right methods. Our existing internal services already have these methods, so wiring them up is a plain assignment, with no extra adapter code.

// internal/service — the real service already matches the interface.
// This compile-time line catches it if a signature ever drifts.
var _ pdk.APIs = (*APIService)(nil)

// internal/server — building pdk.Deps is just assignment.
pdkDeps := &pdk.Deps{
    APIs:          apiService,          // *service.APIService     -> pdk.APIs
    Gateways:      gatewayService,      // *service.GatewayService -> pdk.Gateways
    Subscriptions: subscriptionService,
    Logger:        slogger,
    Config:        cfg,
}

What this gives us:

• Exposing a capability is one line — add the method to the pdk interface (as long as the service already has it with public types).
• Not exposing something is the default — just leave it off the interface.
• The interface holds the line on types — a pdk method can only use public types, so model.* or repository.* simply can't leak out.
• Signature drift is caught at build time — if someone changes a service method that a pdk interface relies on, var _ pdk.APIs = (*APIService)(nil) stops compiling. That forces a real decision about the public contract before we release.

4.1 The rule: only public types in pdk signatures

Every type used in a pdk interface method must be public: an api.* DTO, a type owned by pdk (like pdk.ListOptions), or a plain built-in type.

For each service method we want to expose, one of two things is true:

• It already uses only public types (most do — they speak api.*). Example: GetGateway(gatewayID, orgID string) (*api.GatewayResponse, error). Just list it as-is.
• It uses an internal type (repository.ListOptions, model.*). Example: ListGateways(orgID *string, opts repository.ListOptions). Give the exposed version a public signature instead — take pdk.ListOptions, or plain values like limit, offset int, or add a small clean method on the service. Convert back to the internal type inside the method, where we're still in internal/.

We do not put pagination in its own query package. The shared ListOptions lives in pdk, because it's part of the public contract and shows up in many capabilities.

5. Server wiring — one loop, two tiers

The two plugin types differ only in the Deps they get. The server keeps a single startup loop by wrapping each external pdk.Plugin so it looks like an internal plugin.Plugin:

// internal/server
type externalPlugin struct {
    p       pdk.Plugin
    pdkDeps *pdk.Deps // built once by the server from the internal services
}

func (e *externalPlugin) Name() string                    { return e.p.Name() }
func (e *externalPlugin) Init(*plugin.Deps) error          { return e.p.Init(e.pdkDeps) }
func (e *externalPlugin) RegisterRoutes(m *http.ServeMux)   { e.p.RegisterRoutes(m) }
func (e *externalPlugin) OpenAPISpec() []byte              { return e.p.OpenAPISpec() }
func (e *externalPlugin) Shutdown(c context.Context) error { return e.p.Shutdown(c) }
// AuthSkipPathProvider forwarded via type assertion

The server takes both tiers:

func StartPlatformAPIServer(cfg *config.Server, slogger *slog.Logger,
    internal []plugin.Plugin, // built-ins — full Deps
    external []pdk.Plugin,    // wrappers — pdk.Deps
) (*Server, error)

• cmd/main.go → internal = builtinPlugins(), external = nil.
• platform.App.Run → internal = nil, external = a.plugins (from WithPlugin).

Both tiers then go through the same loop (Init → merge OpenAPI scopes → RegisterRoutes → optional AuthSkipPathProvider / core-service hooks) and are shut down the same way.

5.1 The platform façade

platform is the package a wrapper imports to build and run the server: New, Run, and the With* options. It's the only package a wrapper needs to start things; pdk is the package it builds its plugins against. The split is clean — platform runs the server, pdk says what a plugin is and what it can reach.

The façade works in terms of the external surface (pdk) and never exposes internal/plugin. It aliases the two contract types, so a wrapper can call them either platform.Plugin / platform.Deps or pdk.Plugin / pdk.Deps (we can drop the aliases if we'd rather make wrappers import pdk directly):

// platform/platform.go
import "github.com/wso2/api-platform/platform-api/pdk"

// Plugin is what a wrapper implements — it gets the pdk.Deps, not raw repositories.
type Plugin = pdk.Plugin

// Deps is the set of capabilities passed to a plugin's Init.
type Deps = pdk.Deps

type App struct { /* cfg, logger, … */ plugins []pdk.Plugin }

func (a *App) Run() error {
    // Wrappers only ever supply external (pdk) plugins; there are no built-ins
    // from the façade — cmd/main.go supplies those directly (see Section 5).
    srv, err := server.StartPlatformAPIServer(a.cfg, a.logger, nil, a.plugins)
    // …
}

// platform/options.go
func WithPlugin(plugins ...pdk.Plugin) Option {
    return func(a *App) {
        for _, p := range plugins {
            if p == nil { continue }
            a.plugins = append(a.plugins, p)
        }
    }
}

So a wrapper's main looks like this:

app, err := platform.New(
    platform.WithConfigPath("config.toml"),
    platform.WithPlugin(&cloud.CloudPlugin{ /* own repos injected here */ }),
)
if err != nil { log.Fatal(err) }
log.Fatal(app.Run())

Two things follow from the façade working in terms of pdk:

• A wrapper plugin implements pdk.Plugin and gets pdk.Deps in Init — the capabilities (deps.APIs.…, deps.Gateways.…), never raw repositories or the DB. The type system makes sure of this.
• The request helpers come from pdk (pdk.OrganizationFromRequest, …). platform can keep thin aliases for convenience — see Section 9 step 4.

The built-in tier does not go through platform: cmd/main.go passes builtinPlugins() straight into StartPlatformAPIServer as the internal argument, and they keep their full plugin.Deps.

5.2 Plugins can add middleware to the HTTP chain

Today the server wraps the mux in a fixed chain (see internal/server/server.go):

CORS → auth → organization resolver → scope enforcer → mux

A plugin can add its own middleware at one of two fixed spots — before this chain or after it. We expose only these two on purpose. It lets a plugin either wrap the whole request or run with the authenticated identity, without freezing the internal order of the platform's own middleware (which we want to stay free to change). We do not let a plugin insert middleware between platform steps (say, between auth and the scope enforcer) — that would turn the internal chain order into part of the public contract.

The two spots

• Before the chain (outermost). Runs first, on every request, before CORS and auth. There is no authenticated identity 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: the org comes from platform middleware, never from a plugin.
• After the chain (innermost). 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 the pdk request helpers. Good for per-tenant rate limiting, audit, or request enrichment. It must still scope by the org from context (GO-AUTH-005).

The pdk surface

// pdk/middleware.go
package pdk

// Middleware is a standard Go middleware — it wraps one handler with another.
type Middleware func(http.Handler) http.Handler

type ChainPosition int

const (
    // BeforePlatformChain: outermost. Runs before CORS/auth, on every request,
    // with no authenticated identity in the context yet.
    BeforePlatformChain ChainPosition = iota
    // AfterPlatformChain: innermost. Runs after auth + scope enforcement, just
    // before routing, with the authenticated identity available.
    AfterPlatformChain
)

type PositionedMiddleware struct {
    Position ChainPosition
    Wrap     Middleware
}

// MiddlewareProvider is an OPTIONAL interface a Plugin may implement (like
// AuthSkipPathProvider). Return an empty slice to add none.
type MiddlewareProvider interface {
    Middleware() []PositionedMiddleware
}

Server wiring

The server already collects things from each plugin in its startup loop (skip-paths, OpenAPI scopes). It collects middleware the same way, then slots the two groups into the chain when it builds it:

// internal/server — during the plugin loop
var preChain, postChain []pdk.Middleware
for _, p := range plugins {
    // The externalPlugin wrapper forwards this for external plugins, so both
    // tiers are handled by the same check (same pattern as AuthSkipPathProvider).
    if mp, ok := p.(plugin.MiddlewareProvider); ok {
        for _, m := range mp.Middleware() {
            switch m.Position {
            case pdk.BeforePlatformChain:
                preChain = append(preChain, m.Wrap)
            case pdk.AfterPlatformChain:
                postChain = append(postChain, m.Wrap)
            }
        }
    }
}

// ... later, where the chain is built today:
var chain []func(http.Handler) http.Handler
chain = append(chain, preChain...)          // plugin "before" — outermost
chain = append(chain, corsMiddleware)       // existing
chain = append(chain, authMiddleware...)     // existing
chain = append(chain, orgResolverMiddleware) // existing
chain = append(chain, scopeEnforcer)         // existing
chain = append(chain, postChain...)         // plugin "after" — innermost, before the mux
handler := gohttpkit.Chain(chain...)(mux)

Notes:

• Within a spot, middleware runs in plugin registration order.
• plugin.MiddlewareProvider mirrors pdk.MiddlewareProvider (the same mirror-and-forward setup used for AuthSkipPathProvider today), so internal and external plugins share one wiring path.

Example (external plugin)

func (p *CloudPlugin) Middleware() []pdk.PositionedMiddleware {
    return []pdk.PositionedMiddleware{
        {
            Position: pdk.BeforePlatformChain, // outermost — before auth, no identity yet
            Wrap: func(next http.Handler) http.Handler {
                return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
                    // attach a correlation ID before anything else runs
                    id := r.Header.Get("X-Request-ID")
                    if id == "" {
                        id = newRequestID() // crypto/rand, no source tags
                    }
                    w.Header().Set("X-Request-ID", id)
                    next.ServeHTTP(w, r.WithContext(context.WithValue(r.Context(), requestIDKey, id)))
                })
            },
        },
        {
            Position: pdk.AfterPlatformChain, // innermost — after auth + scope, identity available
            Wrap: func(next http.Handler) http.Handler {
                return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
                    start := time.Now()
                    next.ServeHTTP(w, r)
                    // the authenticated org is in the context now — read it there, never from input (GO-AUTH-005)
                    orgID, _ := pdk.OrganizationFromRequest(r)
                    reqID, _ := r.Context().Value(requestIDKey).(string)
                    p.deps.Logger.Info("api-cloud: request",
                        "method", r.Method, "path", r.URL.Path,
                        "org", orgID, "requestId", reqID,
                        "durationMs", time.Since(start).Milliseconds())
                })
            },
        },
    }
}

6. Package layout

platform-api/
├── api/          PUBLIC  wire DTOs (exists) — the shared vocabulary
├── pdk/          PUBLIC  external contract: Plugin, Deps, capability interfaces,
│                          ListOptions, request accessors, middleware types (Section 5.2)
│                          (imports only api + config + stdlib)
├── platform/     PUBLIC  runtime façade: App / New / Run, WithPlugin(pdk.Plugin)
└── internal/
      ├── plugin/       internal-tier Plugin + FULL Deps (raw repos + services)
      ├── service/      concrete services — STAY internal (match pdk.* by shape)
      ├── repository/   interfaces + SQL impls — STAY internal
      ├── model/        DB structs — STAY internal
      ├── server/       builds pdk.Deps, wraps external plugins, runs the loop
      └── handler/, middleware/, …

The only new public package is pdk. service, repository, and model all stay in internal/: the pdk interfaces speak api.*, so model never has to be made public.

7. What we promise not to break

• pdk + api are the whole promise. Version them, and review any change to them carefully.
• internal/service and below can change freely. The var _ pdk.APIs = (*APIService)(nil) lines turn any breaking change into a build error in our own code, before we release.
• Internal plugins don't count — they are rebuilt in-tree against whatever the internal APIs currently are.

8. What building a plugin feels like, per tier

Internal (eventgateway): implement internal/plugin.Plugin; use deps.APIRepo, the concrete services, the DB — full access. Put it behind the experimental build tag. Ship it when it's ready.

External (api-cloud): implement pdk.Plugin and grab the pdk.Deps in Init. One plugin holds the whole api-cloud extension — not one plugin per resource. It keeps its own data (its own repositories, wired up by api-cloud, not by the PDK) and uses the PDK to fill in data from platform-api. It registers the routes for all api-cloud resources in one RegisterRoutes, and grows by adding more handlers and more repositories to the same plugin.

Environments is one such resource: api-cloud stores each environment (including the ID of the gateway it's linked to) in its own repository, then calls deps.Gateways to get that gateway's details from platform-api. The repositories inside platform-api are out of reach — the type system won't allow it.

// CloudPlugin holds all of api-cloud's routes. It has api-cloud's OWN
// repositories, plus the platform-api capabilities from the PDK.
type CloudPlugin struct {
    deps      *pdk.Deps       // platform-api capabilities — set in Init
    envRepo   *cloud.EnvRepo  // api-cloud's OWN store — wired up by api-cloud, not the PDK
    // ... more api-cloud repositories as the extension grows
}

func (p *CloudPlugin) Name() string                   { return "api-cloud" }
func (p *CloudPlugin) Init(d *pdk.Deps) error          { p.deps = d; return nil }
func (p *CloudPlugin) OpenAPISpec() []byte            { return cloudSpec }
func (p *CloudPlugin) Shutdown(context.Context) error  { return nil }

func (p *CloudPlugin) RegisterRoutes(mux *http.ServeMux) {
    mux.HandleFunc("GET /api/cloud/v1/environments/{id}", p.getEnvironment)
    // ... other api-cloud resources register their routes here too
}

// getEnvironment returns an api-cloud environment, with the linked gateway's
// details filled in from platform-api via the PDK.
func (p *CloudPlugin) getEnvironment(w http.ResponseWriter, r *http.Request) {
    orgID, ok := pdk.OrganizationFromRequest(r) // org from the context (GO-AUTH-005)
    if !ok { /* 403 */ return }

    envID := r.PathValue("id")

    // 1. Look up the environment in api-cloud's OWN repository. It holds the ID
    //    of the gateway this environment is linked to. Scoped by orgID from the
    //    context, never from input (GO-AUTH-005).
    env, err := p.envRepo.GetEnvironment(r.Context(), orgID, envID)
    if err != nil { /* 404 / 500 */ return }

    // 2. Ask platform-api, through the PDK, for that gateway's details.
    gw, err := p.deps.Gateways.GetGateway(env.GatewayID, orgID)
    if err != nil { /* 500 */ return }

    // 3. Put both together into the api-cloud response.
    // ... write { "id": env.ID, "name": env.Name, "gateway": gw, ... }
}