sdk

package
v2.2.2 Latest Latest
Warning

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

 Go to latest Published: Oct 12, 2026 License: AGPL-3.0 Imports: 17 Imported by: 0

Documentation

Overview

plugins/sdk/conversions.go

plugins/sdk/event_service.go Host-side implementation of PluginEventService for microgateway. This server is registered on the go-plugin broker and called by plugins to publish events and subscribe to event streams.

plugins/sdk/grpc_servers.go

plugins/sdk/grpc_wrappers.go

plugins/sdk/plugin.go

Index

Constants

View Source 
const (
	HookTypePreAuth        = interfaces.HookTypePreAuth
	HookTypeAuth           = interfaces.HookTypeAuth
	HookTypePostAuth       = interfaces.HookTypePostAuth
	HookTypeOnResponse     = interfaces.HookTypeOnResponse
	HookTypeDataCollection = interfaces.HookTypeDataCollection
)

Re-export constants for convenience

Variables

View Source 
var HandshakeConfig = plugin.HandshakeConfig{
	ProtocolVersion:  1,
	MagicCookieKey:   "AI_STUDIO_PLUGIN",
	MagicCookieValue: "v1",
}

HandshakeConfig is used for handshaking with the main microgateway process Updated to use unified AI_STUDIO_PLUGIN handshake for polyglot plugin support

Functions

func DeletePluginKV 

func DeletePluginKV(ctx context.Context, key string) (bool, error)

DeletePluginKV deletes a key-value entry for the calling plugin

func ExtractBrokerIDFromConfig 

func ExtractBrokerIDFromConfig(config map[string]string) uint32

ExtractBrokerIDFromConfig extracts the broker ID from plugin config Call this in your Initialize method

func ExtractPluginIDFromConfig 

func ExtractPluginIDFromConfig(config map[string]string) uint32

ExtractPluginIDFromConfig extracts the plugin ID from config

func GetApp 

func GetApp(ctx context.Context, appID uint32) (*pb.GetAppResponse, error)

GetApp returns details for a specific application

func GetAppsCount 

func GetAppsCount(ctx context.Context) (int, error)

GetAppsCount returns the total number of apps

func GetBudgetStatus 

func GetBudgetStatus(ctx context.Context, appID uint32, llmID *uint32) (*pb.GetBudgetStatusResponse, error)

GetBudgetStatus returns budget status for an app

func GetLLM 

func GetLLM(ctx context.Context, llmID uint32) (*pb.GetLLMResponse, error)

GetLLM returns details for a specific LLM

func GetLLMsCount 

func GetLLMsCount(ctx context.Context) (int, error)

GetLLMsCount returns the total number of LLMs

func GetModelPrice 

func GetModelPrice(ctx context.Context, modelName, vendor string) (*pb.GetModelPriceResponse, error)

GetModelPrice returns price for a specific model

func GetSharedBrokerConnection 

func GetSharedBrokerConnection() *grpc.ClientConn

GetSharedBrokerConnection returns the shared gRPC connection to the host's brokered server. This allows other services (like the event service) to reuse the same connection. The go-plugin broker only allows ONE connection per broker ID.

func InitializeServiceAPI 

func InitializeServiceAPI(server *grpc.Server, broker *goplugin.GRPCBroker, pluginIDVal uint32) error

Initialize sets up the SDK with broker access This is called from the plugin's GRPCServer method

func IsEnterprise 

func IsEnterprise(ctx context.Context) (bool, error)

IsEnterprise returns true if the microgateway is running in enterprise mode This is a convenience function that checks if license type is "enterprise"

func IsInitialized 

func IsInitialized() bool

IsInitialized returns whether the SDK has been initialized

func ListApps 

func ListApps(ctx context.Context, page, limit int32, isActive *bool) (*pb.ListAppsResponse, error)

ListApps returns a list of applications

func ListLLMs 

func ListLLMs(ctx context.Context, page, limit int32, vendor string, isActive *bool) (*pb.ListLLMsResponse, error)

ListLLMs returns a list of LLMs from the microgateway

func ListModelPrices 

func ListModelPrices(ctx context.Context, vendor string) (*pb.ListModelPricesResponse, error)

ListModelPrices returns a list of model prices

func ReadPluginKV 

func ReadPluginKV(ctx context.Context, key string) ([]byte, error)

ReadPluginKV reads a key-value entry for the calling plugin

func ReadPluginKVJSON 

func ReadPluginKVJSON(ctx context.Context, key string, target interface{}) error

ReadPluginKVJSON reads and unmarshals a JSON value from KV storage

func SendToControl 

func SendToControl(ctx context.Context, payload []byte, correlationID string, metadata map[string]string) (int64, error)

SendToControl queues a payload to be sent to the AI Studio control plane This is used by plugins running on edge (microgateway) instances to send arbitrary data back to the control plane where it will be routed to the corresponding plugin via AcceptEdgePayload.

Parameters:

  • ctx: Context for the RPC call
  • payload: Arbitrary binary data (max 1MB)
  • correlationID: Optional correlation ID for tracking (can be empty)
  • metadata: Optional key-value metadata (can be nil)

Returns:

  • pendingCount: Number of payloads currently pending in the queue
  • error: Error if the payload could not be queued

func SendToControlJSON 

func SendToControlJSON(ctx context.Context, value interface{}, correlationID string, metadata map[string]string) (int64, error)

SendToControlJSON is a convenience function that JSON-encodes a value and sends it to control

func ServePlugin 

func ServePlugin(impl interface{})

ServePlugin serves a plugin implementation via gRPC Now serves BOTH the main plugin service AND the config provider service

func SetPluginID 

func SetPluginID(id uint32)

SetPluginID updates the plugin ID after it's received from config

func SetServiceBrokerID 

func SetServiceBrokerID(brokerID uint32)

SetServiceBrokerID stores the broker ID for dialing back to host services This is called when the plugin receives the broker ID from config

func SetSharedBrokerConnection 

func SetSharedBrokerConnection(conn *grpc.ClientConn)

SetSharedBrokerConnection stores a pre-dialed gRPC connection for shared use. This is called by services that dial the broker first.

func StoreApp 

func StoreApp(ctx context.Context, req *pb.StoreAppRequest) (*pb.StoreAppResponse, error)

StoreApp writes an App into the local gateway database using upsert semantics. Used by auth plugins that dynamically provision apps from the control plane.

func ValidateCredential 

func ValidateCredential(ctx context.Context, secret string) (*pb.ValidateCredentialResponse, error)

ValidateCredential validates a credential secret

func WritePluginKV 

func WritePluginKV(ctx context.Context, key string, value []byte, expireAt *time.Time) (bool, error)

WritePluginKV writes a key-value entry for the calling plugin Returns true if a new entry was created, false if an existing entry was updated expireAt is optional - pass nil for no expiration

func WritePluginKVJSON 

func WritePluginKVJSON(ctx context.Context, key string, value interface{}) (bool, error)

WritePluginKVJSON writes a JSON-encodable value to KV storage without expiration

func WritePluginKVJSONWithTTL 

func WritePluginKVJSONWithTTL(ctx context.Context, key string, value interface{}, ttl time.Duration) (bool, error)

WritePluginKVJSONWithTTL writes a JSON-encodable value to KV storage with a TTL

func WritePluginKVWithTTL 

func WritePluginKVWithTTL(ctx context.Context, key string, value []byte, ttl time.Duration) (bool, error)

WritePluginKVWithTTL is a convenience function that writes a key-value entry with a TTL (time-to-live) The expiration time is calculated as time.Now().Add(ttl)

Types

type AnalyticsData 

type AnalyticsData = interfaces.AnalyticsData

Re-export interfaces for convenience

type AuthGRPCServer 

type AuthGRPCServer struct {
	BaseGRPCServer
	Impl interfaces.AuthPlugin
}

Auth plugin gRPC server

func (*AuthGRPCServer) Authenticate 

func (s *AuthGRPCServer) Authenticate(ctx context.Context, req *pb.AuthRequest) (*pb.AuthResponse, error)

func (*AuthGRPCServer) Initialize 

func (s *AuthGRPCServer) Initialize(ctx context.Context, req *pb.InitRequest) (*pb.InitResponse, error)

type AuthPlugin 

type AuthPlugin = interfaces.AuthPlugin

Re-export interfaces for convenience

type AuthPluginGRPC 

type AuthPluginGRPC struct {
	plugin.Plugin
	Impl interfaces.AuthPlugin
}

AuthPluginGRPC implements the plugin.Plugin interface for auth plugins

func (*AuthPluginGRPC) GRPCClient 

func (p *AuthPluginGRPC) GRPCClient(ctx context.Context, broker *plugin.GRPCBroker, c *grpc.ClientConn) (interface{}, error)

func (*AuthPluginGRPC) GRPCServer 

func (p *AuthPluginGRPC) GRPCServer(broker *plugin.GRPCBroker, s *grpc.Server) error

type AuthRequest 

type AuthRequest = interfaces.AuthRequest

Re-export interfaces for convenience

type AuthResponse 

type AuthResponse = interfaces.AuthResponse

Re-export interfaces for convenience

type BaseGRPCServer 

type BaseGRPCServer struct {
	pb.UnimplementedPluginServiceServer
	BaseImpl interfaces.BasePlugin
}

Base gRPC server implementation

func (*BaseGRPCServer) GetConfigSchema 

func (s *BaseGRPCServer) GetConfigSchema(ctx context.Context, req *pb.GetConfigSchemaRequest) (*pb.GetConfigSchemaResponse, error)

func (*BaseGRPCServer) Initialize 

func (s *BaseGRPCServer) Initialize(ctx context.Context, req *pb.InitRequest) (*pb.InitResponse, error)

func (*BaseGRPCServer) Ping 

func (s *BaseGRPCServer) Ping(ctx context.Context, req *pb.PingRequest) (*pb.PingResponse, error)

func (*BaseGRPCServer) Shutdown 

func (s *BaseGRPCServer) Shutdown(ctx context.Context, req *pb.ShutdownRequest) (*pb.ShutdownResponse, error)

type BasePlugin 

type BasePlugin = interfaces.BasePlugin

Re-export interfaces for convenience

type BudgetUsageData 

type BudgetUsageData = interfaces.BudgetUsageData

Re-export interfaces for convenience

type ConfigProviderGRPC 

type ConfigProviderGRPC struct {
	configpb.UnimplementedConfigProviderServiceServer
	Impl interfaces.BasePlugin
}

ConfigProviderGRPC server - Isolated service for configuration schema extraction

func (*ConfigProviderGRPC) GetConfigSchema 

func (s *ConfigProviderGRPC) GetConfigSchema(ctx context.Context, req *configpb.ConfigSchemaRequest) (*configpb.ConfigSchemaResponse, error)

func (*ConfigProviderGRPC) GetManifest 

func (s *ConfigProviderGRPC) GetManifest(ctx context.Context, req *configpb.GetManifestRequest) (*configpb.GetManifestResponse, error)

func (*ConfigProviderGRPC) Ping 

func (s *ConfigProviderGRPC) Ping(ctx context.Context, req *configpb.ConfigPingRequest) (*configpb.ConfigPingResponse, error)

type ConfigProviderPluginGRPC 

type ConfigProviderPluginGRPC struct {
	plugin.Plugin
	Impl interfaces.BasePlugin
}

ConfigProviderPluginGRPC implements the plugin.Plugin interface for config-only service

func (*ConfigProviderPluginGRPC) GRPCClient 

func (p *ConfigProviderPluginGRPC) GRPCClient(ctx context.Context, broker *plugin.GRPCBroker, c *grpc.ClientConn) (interface{}, error)

func (*ConfigProviderPluginGRPC) GRPCServer 

func (p *ConfigProviderPluginGRPC) GRPCServer(broker *plugin.GRPCBroker, s *grpc.Server) error

type DataCollectionGRPCServer 

type DataCollectionGRPCServer struct {
	BaseGRPCServer
	Impl interfaces.DataCollectionPlugin
}

Data collection plugin gRPC server

func (*DataCollectionGRPCServer) HandleAnalytics 

func (s *DataCollectionGRPCServer) HandleAnalytics(ctx context.Context, req *pb.AnalyticsRequest) (*pb.DataCollectionResponse, error)

func (*DataCollectionGRPCServer) HandleBudgetUsage 

func (s *DataCollectionGRPCServer) HandleBudgetUsage(ctx context.Context, req *pb.BudgetUsageRequest) (*pb.DataCollectionResponse, error)

func (*DataCollectionGRPCServer) HandleProxyLog 

func (s *DataCollectionGRPCServer) HandleProxyLog(ctx context.Context, req *pb.ProxyLogRequest) (*pb.DataCollectionResponse, error)

func (*DataCollectionGRPCServer) Initialize 

func (s *DataCollectionGRPCServer) Initialize(ctx context.Context, req *pb.InitRequest) (*pb.InitResponse, error)

type DataCollectionPlugin 

type DataCollectionPlugin = interfaces.DataCollectionPlugin

Re-export interfaces for convenience

type DataCollectionPluginGRPC 

type DataCollectionPluginGRPC struct {
	plugin.Plugin
	Impl interfaces.DataCollectionPlugin
}

DataCollectionPluginGRPC implements the plugin.Plugin interface for data collection plugins

func (*DataCollectionPluginGRPC) GRPCClient 

func (p *DataCollectionPluginGRPC) GRPCClient(ctx context.Context, broker *plugin.GRPCBroker, c *grpc.ClientConn) (interface{}, error)

func (*DataCollectionPluginGRPC) GRPCServer 

func (p *DataCollectionPluginGRPC) GRPCServer(broker *plugin.GRPCBroker, s *grpc.Server) error

type DataCollectionResponse 

type DataCollectionResponse = interfaces.DataCollectionResponse

Re-export interfaces for convenience

type EnrichedRequest 

type EnrichedRequest = interfaces.EnrichedRequest

Re-export interfaces for convenience

type HeadersRequest 

type HeadersRequest = interfaces.HeadersRequest

Re-export interfaces for convenience

type HeadersResponse 

type HeadersResponse = interfaces.HeadersResponse

Re-export interfaces for convenience

type HookType 

type HookType = interfaces.HookType

Re-export interfaces for convenience

type LicenseInfo 

type LicenseInfo struct {
	Valid        bool     // Whether license is currently valid
	DaysLeft     int      // Days until license expires (-1 = never expires)
	Type         string   // "community" or "enterprise"
	Entitlements []string // List of enabled features/entitlements
	Organization string   // Organization name from license (if any)
}

LicenseInfo contains license information returned by GetLicenseInfo

func GetLicenseInfo 

func GetLicenseInfo(ctx context.Context) (*LicenseInfo, error)

GetLicenseInfo returns license information from the host This can be used by plugins to check if enterprise features are available All plugins can call this without requiring special scopes

type PluginContext 

type PluginContext = interfaces.PluginContext

Re-export interfaces for convenience

type PluginEventServer 

type PluginEventServer struct {
	pb.UnimplementedPluginEventServiceServer
	// contains filtered or unexported fields
}

PluginEventServer implements the PluginEventServiceServer interface. It bridges plugin event requests to the local eventbridge.Bus.

func NewPluginEventServer 

func NewPluginEventServer(bus eventbridge.Bus, nodeID string) *PluginEventServer

NewPluginEventServer creates a new PluginEventServer instance. The bus parameter is the local event bus to publish/subscribe to. The nodeID identifies this node for event origin tracking.

func (*PluginEventServer) CleanupAllSubscriptions 

func (s *PluginEventServer) CleanupAllSubscriptions()

CleanupAllSubscriptions removes all active subscriptions. Called during shutdown.

func (*PluginEventServer) GetActiveSubscriptionCount 

func (s *PluginEventServer) GetActiveSubscriptionCount() int

GetActiveSubscriptionCount returns the number of active subscriptions. Useful for monitoring and debugging.

func (*PluginEventServer) Publish 

func (s *PluginEventServer) Publish(ctx context.Context, req *pb.PublishRequest) (*pb.PublishResponse, error)

Publish receives an event from a plugin and publishes it to the local bus. The event will be routed based on its direction field.

func (*PluginEventServer) Subscribe 

func (s *PluginEventServer) Subscribe(req *pb.SubscribeRequest, stream grpc.ServerStreamingServer[pb.EventMessage]) error

Subscribe creates a subscription and streams events back to the plugin. The stream remains open until the client disconnects.

func (*PluginEventServer) Unsubscribe 

func (s *PluginEventServer) Unsubscribe(ctx context.Context, req *pb.UnsubscribeRequest) (*pb.UnsubscribeResponse, error)

Unsubscribe removes a subscription by ID. Note: This is optional since subscriptions are automatically cleaned up when the Subscribe stream closes.

type PluginRequest 

type PluginRequest = interfaces.PluginRequest

Re-export interfaces for convenience

type PluginResponse 

type PluginResponse = interfaces.PluginResponse

Re-export interfaces for convenience

type PostAuthGRPCServer 

type PostAuthGRPCServer struct {
	BaseGRPCServer
	Impl interfaces.PostAuthPlugin
}

Post-auth plugin gRPC server

func (*PostAuthGRPCServer) Initialize 

func (s *PostAuthGRPCServer) Initialize(ctx context.Context, req *pb.InitRequest) (*pb.InitResponse, error)

func (*PostAuthGRPCServer) ProcessPostAuth 

func (s *PostAuthGRPCServer) ProcessPostAuth(ctx context.Context, req *pb.EnrichedRequest) (*pb.PluginResponse, error)

type PostAuthPlugin 

type PostAuthPlugin = interfaces.PostAuthPlugin

Re-export interfaces for convenience

type PostAuthPluginGRPC 

type PostAuthPluginGRPC struct {
	plugin.Plugin
	Impl interfaces.PostAuthPlugin
}

PostAuthPluginGRPC implements the plugin.Plugin interface for post-auth plugins

func (*PostAuthPluginGRPC) GRPCClient 

func (p *PostAuthPluginGRPC) GRPCClient(ctx context.Context, broker *plugin.GRPCBroker, c *grpc.ClientConn) (interface{}, error)

func (*PostAuthPluginGRPC) GRPCServer 

func (p *PostAuthPluginGRPC) GRPCServer(broker *plugin.GRPCBroker, s *grpc.Server) error

type PreAuthGRPCServer 

type PreAuthGRPCServer struct {
	BaseGRPCServer
	Impl interfaces.PreAuthPlugin
}

Pre-auth plugin gRPC server

func (*PreAuthGRPCServer) Initialize 

func (s *PreAuthGRPCServer) Initialize(ctx context.Context, req *pb.InitRequest) (*pb.InitResponse, error)

func (*PreAuthGRPCServer) ProcessPreAuth 

func (s *PreAuthGRPCServer) ProcessPreAuth(ctx context.Context, req *pb.PluginRequest) (*pb.PluginResponse, error)

type PreAuthPlugin 

type PreAuthPlugin = interfaces.PreAuthPlugin

Re-export interfaces for convenience

type PreAuthPluginGRPC 

type PreAuthPluginGRPC struct {
	plugin.Plugin
	Impl interfaces.PreAuthPlugin
}

PreAuthPluginGRPC implements the plugin.Plugin interface for pre-auth plugins

func (*PreAuthPluginGRPC) GRPCClient 

func (p *PreAuthPluginGRPC) GRPCClient(ctx context.Context, broker *plugin.GRPCBroker, c *grpc.ClientConn) (interface{}, error)

func (*PreAuthPluginGRPC) GRPCServer 

func (p *PreAuthPluginGRPC) GRPCServer(broker *plugin.GRPCBroker, s *grpc.Server) error

type ProxyLogData 

type ProxyLogData = interfaces.ProxyLogData

Data collection types

type ResponseData 

type ResponseData = interfaces.ResponseData

Re-export interfaces for convenience

type ResponseGRPCServer 

type ResponseGRPCServer struct {
	BaseGRPCServer
	Impl interfaces.ResponsePlugin
}

Response plugin gRPC server (new clean interface)

func (*ResponseGRPCServer) Initialize 

func (s *ResponseGRPCServer) Initialize(ctx context.Context, req *pb.InitRequest) (*pb.InitResponse, error)

func (*ResponseGRPCServer) OnBeforeWrite 

func (s *ResponseGRPCServer) OnBeforeWrite(ctx context.Context, req *pb.ResponseWriteRequest) (*pb.ResponseWriteResponse, error)

func (*ResponseGRPCServer) OnBeforeWriteHeaders 

func (s *ResponseGRPCServer) OnBeforeWriteHeaders(ctx context.Context, req *pb.HeadersRequest) (*pb.HeadersResponse, error)

type ResponsePlugin 

type ResponsePlugin = interfaces.ResponsePlugin

Re-export interfaces for convenience

type ResponsePluginGRPC 

type ResponsePluginGRPC struct {
	plugin.Plugin
	Impl interfaces.ResponsePlugin
}

ResponsePluginGRPC implements the plugin.Plugin interface for response plugins

func (*ResponsePluginGRPC) GRPCClient 

func (p *ResponsePluginGRPC) GRPCClient(ctx context.Context, broker *plugin.GRPCBroker, c *grpc.ClientConn) (interface{}, error)

func (*ResponsePluginGRPC) GRPCServer 

func (p *ResponsePluginGRPC) GRPCServer(broker *plugin.GRPCBroker, s *grpc.Server) error

type ResponseWriteRequest 

type ResponseWriteRequest = interfaces.ResponseWriteRequest

Re-export interfaces for convenience

type ResponseWriteResponse 

type ResponseWriteResponse = interfaces.ResponseWriteResponse

Re-export interfaces for convenience

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.