packagebridge

type Allowlist ¶

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

Allowlist binds every bridge operation to one package and v2 route id.

func NewAllowlist(operations ...Operation) (*Allowlist, error)

func NewAllowlistWithFallback(fallback OperationResolver, operations ...Operation) (*Allowlist, error)

func (a *Allowlist) Allows(packageID, routeID, operation string) bool

func (a *Allowlist) Invoke(ctx context.Context, call Call) (Response, error)

type Call ¶

type Call struct {
	Host      HostIdentity
	Request   Request
	Operation string
	Payload   []byte
}

Call is delivered only after a capability, package identity, route, and operation have all been verified.

type Factory ¶

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

func NewFactory(allowlist *Allowlist, webSocketResolvers ...WebSocketOperationResolver) *Factory

func (f *Factory) NewSession(identity HostIdentity) (*Session, *os.File, error)

type Header ¶

type Header struct {
	Name  string
	Value string
}

type HostIdentity ¶

type HostIdentity struct {
	PackageID  string
	Version    string
	Generation uint64
}

HostIdentity is fixed when a child process is started. The socketpair makes this identity process-local rather than client-asserted.

type Operation ¶

type Operation struct {
	PackageID string
	RouteID   string
	Name      string
	Handler   OperationHandler
}

type OperationHandler ¶

type OperationHandler func(context.Context, Call) (Response, error)

func NewHTTPAdapter(handler gin.HandlerFunc) OperationHandler

type OperationResolver ¶

type OperationResolver interface {
	Resolve(packageID, routeID, operation string) (OperationHandler, bool)
}

OperationResolver provides an additional exact operation source. It is used for handlers registered during router construction, not for path matching or arbitrary package-supplied operation names.

type Request ¶

type Request struct {
	RequestID     string
	RouteID       string
	Method        string
	Body          []byte
	PrincipalJSON []byte
	MetadataJSON  []byte
	Deadline      time.Time
}

Request is kernel-derived request state retained behind a capability. A package never supplies these values to the bridge RPC.

type Response ¶

type Response struct {
	StatusCode uint32
	Body       []byte
	Headers    []Header
}

Response is an explicit parent-produced answer to one allowed bridge operation. Package code cannot obtain this authority except by consuming a verified capability.

type RouteRegistry ¶

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

RouteRegistry is populated only while Gin routes are constructed. It keeps the legacy-compatible handler behind the kernel's exact bridge operation checks; it does not inspect package-controlled paths or route declarations.

func DefaultRouteRegistry() *RouteRegistry

func NewRouteRegistry() *RouteRegistry

func (r *RouteRegistry) Allowlist() *Allowlist

func (r *RouteRegistry) MustRegister(packageID, routeID string, handler gin.HandlerFunc)

func (r *RouteRegistry) MustRegisterWebSocket(packageID, routeID string, handler gin.HandlerFunc)

func (r *RouteRegistry) Register(packageID, routeID string, handler gin.HandlerFunc) error

func (r *RouteRegistry) RegisterWebSocket(packageID, routeID string, handler gin.HandlerFunc) error

func (r *RouteRegistry) Resolve(packageID, routeID, operation string) (OperationHandler, bool)

func (r *RouteRegistry) ResolveWebSocket(packageID, routeID, operation string) (WebSocketOperationHandler, bool)

type Session ¶

type Session struct {
	packagebridgev1.UnimplementedKernelPackageBridgeServer
	// contains filtered or unexported fields
}

Session owns one endpoint of an inherited Unix socketpair. The returned child file is passed once through exec.ExtraFiles and is never addressable by a filesystem path.

func NewSession(identity HostIdentity, handler *Allowlist, webSocketResolvers ...WebSocketOperationResolver) (*Session, *os.File, error)

func (s *Session) Close() error

func (s *Session) Invoke(ctx context.Context, request *packagebridgev1.InvokeRequest) (*packagebridgev1.InvokeResponse, error)

func (s *Session) Mint(request Request) ([]byte, error)

func (s *Session) OpenWebSocket(stream packagebridgev1.KernelPackageBridge_OpenWebSocketServer) error

func (s *Session) Revoke(raw []byte)

type SessionFactory ¶

type SessionFactory interface {
	NewSession(HostIdentity) (*Session, *os.File, error)
}

SessionFactory creates a fresh private endpoint for every supervised host.

type WebSocketClose ¶

type WebSocketClose struct {
	Code   uint32
	Reason string
}

type WebSocketFrame ¶

type WebSocketFrame struct {
	Data  []byte
	Close *WebSocketClose
}

WebSocketFrame is a post-open bridge frame. A nil Close denotes a data frame, including an empty payload.

type WebSocketOperationHandler ¶

type WebSocketOperationHandler func(context.Context, Call, WebSocketStream) error

func NewWebSocketAdapter(handler gin.HandlerFunc) WebSocketOperationHandler

type WebSocketOperationResolver ¶

type WebSocketOperationResolver interface {
	ResolveWebSocket(packageID, routeID, operation string) (WebSocketOperationHandler, bool)
}

WebSocketOperationResolver provides exact streaming operations registered during router construction. It is separate from unary operations so a package cannot upgrade a route merely by changing a declaration.

type WebSocketStream ¶

type WebSocketStream interface {
	Recv() (WebSocketFrame, error)
	Send(WebSocketFrame) error
}

WebSocketStream is the kernel-side end of a private package bridge stream. Exactly one reader and one writer may operate concurrently.