Documentation
¶
Index ¶
- Constants
- Variables
- func CanTransition(from, to SessionState) bool
- func FindFreeTCPPort() (int32, error)
- func IsPortUnavailable(port int32) bool
- func RegisterPlugin(p *sdk.Plugin, opts PluginOpts) error
- type Connection
- type FindPortForwardSessionRequest
- type ForwarderResult
- type Manager
- func (m *Manager) ClosePortForwardSession(_ *types.PluginContext, sessionID string) (*PortForwardSession, error)
- func (m *Manager) FindPortForwardSessions(_ *types.PluginContext, req FindPortForwardSessionRequest) ([]*PortForwardSession, error)
- func (m *Manager) GetPortForwardSession(_ *types.PluginContext, sessionID string) (*PortForwardSession, error)
- func (m *Manager) GetSupportedPortForwardTargets(_ *types.PluginContext) ([]string, error)
- func (m *Manager) ListPortForwardSessions(_ *types.PluginContext) ([]*PortForwardSession, error)
- func (m *Manager) StartPortForwardSession(pluginctx *types.PluginContext, opts PortForwardSessionOptions) (*PortForwardSession, error)
- func (m *Manager) StopAll()
- type ManagerConfig
- type NetworkerError
- func NewForwarderFailedError(sessionID string, err error) *NetworkerError
- func NewInvalidConnectionTypeError(connectionType string) *NetworkerError
- func NewInvalidStateTransitionError(sessionID string, from, to SessionState) *NetworkerError
- func NewManagerShuttingDownError(sessionID string) *NetworkerError
- func NewNoHandlerFoundError(resourceKey string) *NetworkerError
- func NewPortUnavailableError(port int32) *NetworkerError
- func NewSessionNotFoundError(sessionID string) *NetworkerError
- type NetworkerErrorCode
- type Plugin
- type PluginClient
- func (p *PluginClient) ClosePortForwardSession(ctx *types.PluginContext, sessionID string) (*PortForwardSession, error)
- func (p *PluginClient) FindPortForwardSessions(ctx *types.PluginContext, req FindPortForwardSessionRequest) ([]*PortForwardSession, error)
- func (p *PluginClient) GetPortForwardSession(ctx *types.PluginContext, sessionID string) (*PortForwardSession, error)
- func (p *PluginClient) GetSupportedPortForwardTargets(ctx *types.PluginContext) ([]string, error)
- func (p *PluginClient) ListPortForwardSessions(ctx *types.PluginContext) ([]*PortForwardSession, error)
- func (p *PluginClient) StartPortForwardSession(ctx *types.PluginContext, opts PortForwardSessionOptions) (*PortForwardSession, error)
- func (p *PluginClient) StopAll()
- type PluginOpts
- type PluginServer
- func (s *PluginServer) ClosePortForwardSession(ctx context.Context, in *networkerpb.PortForwardSessionByIdRequest) (*networkerpb.PortForwardSessionByIdResponse, error)
- func (s *PluginServer) FindPortForwardSessions(ctx context.Context, in *networkerpb.FindPortForwardSessionRequest) (*networkerpb.PortForwardSessionListResponse, error)
- func (s *PluginServer) GetPortForwardSession(ctx context.Context, in *networkerpb.PortForwardSessionByIdRequest) (*networkerpb.PortForwardSessionByIdResponse, error)
- func (s *PluginServer) GetSupportedPortForwardTargets(ctx context.Context, _ *emptypb.Empty) (*networkerpb.GetSupportedPortForwardTargetsResponse, error)
- func (s *PluginServer) ListPortForwardSessions(ctx context.Context, _ *emptypb.Empty) (*networkerpb.PortForwardSessionListResponse, error)
- func (s *PluginServer) StartPortForwardSession(ctx context.Context, in *networkerpb.PortForwardSessionOptions) (*networkerpb.PortForwardSessionByIdResponse, error)
- type PortChecker
- type PortForwardConnectionType
- type PortForwardProtocol
- type PortForwardProvider
- type PortForwardResourceConnection
- func (c *PortForwardResourceConnection) ToProto() *networkerpb.PortForwardResourceConnection
- func (c *PortForwardResourceConnection) ToSessionOptionsProto() *networkerpb.PortForwardSessionOptions_ResourceConnection
- func (c *PortForwardResourceConnection) ToSessionProto() *networkerpb.PortForwardSession_ResourceConnection
- type PortForwardSession
- type PortForwardSessionEncryption
- type PortForwardSessionOptions
- type PortForwardStaticConnection
- func (c *PortForwardStaticConnection) ToProto() *networkerpb.PortForwardStaticConnection
- func (c *PortForwardStaticConnection) ToSessionOptionsProto() *networkerpb.PortForwardSessionOptions_StaticConnection
- func (c *PortForwardStaticConnection) ToSessionProto() *networkerpb.PortForwardSession_StaticConnection
- type Provider
- type RealPortChecker
- type ResourceForwarder
- type ResourceForwarderFunc
- type ResourcePortForwardHandlerOpts
- type SessionState
- type StaticForwarder
- type StaticForwarderFunc
- type StaticPortForwardHandlerOpts
Constants ¶
const (
PluginID = "networker"
)
Variables ¶
var ( ErrNetSessionNotFound = &NetworkerError{Code: ErrCodeSessionNotFound} ErrNetNoHandlerFound = &NetworkerError{Code: ErrCodeNoHandlerFound} ErrNetForwarderFailed = &NetworkerError{Code: ErrCodeForwarderFailed} ErrNetManagerShuttingDown = &NetworkerError{Code: ErrCodeManagerShuttingDown} ErrNetInvalidStateTransition = &NetworkerError{Code: ErrCodeInvalidStateTransition} ErrNetInvalidConnectionType = &NetworkerError{Code: ErrCodeInvalidConnectionType} )
Sentinel errors for errors.Is matching.
Functions ¶
func CanTransition ¶
func CanTransition(from, to SessionState) bool
CanTransition returns true if transitioning from → to is valid.
func FindFreeTCPPort ¶
FindFreeTCPPort finds an available port by letting the OS pick a free port.
func IsPortUnavailable ¶
IsPortUnavailable checks if a port is unavailable (i.e., in use).
func RegisterPlugin ¶
func RegisterPlugin( p *sdk.Plugin, opts PluginOpts, ) error
Types ¶
type Connection ¶
type Connection interface {
// contains filtered or unexported methods
}
Connection is implemented by PortForwardResourceConnection and PortForwardStaticConnection. The unexported method seals the interface.
type FindPortForwardSessionRequest ¶
type FindPortForwardSessionRequest struct {
ResourceID string `json:"resource_id"`
ConnectionID string `json:"connection_id"`
}
func NewFindPortForwardSessionRequestFromProto ¶
func NewFindPortForwardSessionRequestFromProto( p *networkerpb.FindPortForwardSessionRequest, ) FindPortForwardSessionRequest
func (FindPortForwardSessionRequest) ToProto ¶
func (p FindPortForwardSessionRequest) ToProto() *networkerpb.FindPortForwardSessionRequest
type ForwarderResult ¶
type ForwarderResult struct {
SessionID string
Ready <-chan struct{} // closed when tunnel established
ErrCh <-chan error // receives fatal error; closed on clean exit
}
ForwarderResult carries the outcome of starting a port forward. The Ready channel is closed once the tunnel is established. The ErrCh channel receives a fatal error or is closed on clean exit. The manager monitors ErrCh to detect post-start failures.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager manages the lifecycle of networker actions, such as port forwarding sessions.
func NewManager ¶
func NewManager(cfg ManagerConfig, opts PluginOpts) *Manager
NewManager creates a new Manager with the given config and plugin opts.
func (*Manager) ClosePortForwardSession ¶
func (m *Manager) ClosePortForwardSession( _ *types.PluginContext, sessionID string, ) (*PortForwardSession, error)
func (*Manager) FindPortForwardSessions ¶
func (m *Manager) FindPortForwardSessions( _ *types.PluginContext, req FindPortForwardSessionRequest, ) ([]*PortForwardSession, error)
func (*Manager) GetPortForwardSession ¶
func (m *Manager) GetPortForwardSession( _ *types.PluginContext, sessionID string, ) (*PortForwardSession, error)
func (*Manager) GetSupportedPortForwardTargets ¶
func (m *Manager) GetSupportedPortForwardTargets(_ *types.PluginContext) ([]string, error)
func (*Manager) ListPortForwardSessions ¶
func (m *Manager) ListPortForwardSessions(_ *types.PluginContext) ([]*PortForwardSession, error)
func (*Manager) StartPortForwardSession ¶
func (m *Manager) StartPortForwardSession( pluginctx *types.PluginContext, opts PortForwardSessionOptions, ) (*PortForwardSession, error)
type ManagerConfig ¶
type ManagerConfig struct {
Logger logging.Logger
Settings settings.Provider
PortChecker PortChecker // nil → RealPortChecker
Clock timeutil.Clock // nil → timeutil.RealClock
CloseTimeout time.Duration // default 10s
}
ManagerConfig configures the Manager.
type NetworkerError ¶
type NetworkerError struct {
Code NetworkerErrorCode
SessionID string
Message string
Err error // optional wrapped error
}
NetworkerError is a structured error for networker operations.
func NewForwarderFailedError ¶
func NewForwarderFailedError(sessionID string, err error) *NetworkerError
func NewInvalidConnectionTypeError ¶
func NewInvalidConnectionTypeError(connectionType string) *NetworkerError
func NewInvalidStateTransitionError ¶
func NewInvalidStateTransitionError(sessionID string, from, to SessionState) *NetworkerError
func NewManagerShuttingDownError ¶
func NewManagerShuttingDownError(sessionID string) *NetworkerError
func NewNoHandlerFoundError ¶
func NewNoHandlerFoundError(resourceKey string) *NetworkerError
func NewPortUnavailableError ¶
func NewPortUnavailableError(port int32) *NetworkerError
func NewSessionNotFoundError ¶
func NewSessionNotFoundError(sessionID string) *NetworkerError
func (*NetworkerError) Error ¶
func (e *NetworkerError) Error() string
func (*NetworkerError) Is ¶
func (e *NetworkerError) Is(target error) bool
Is reports whether target matches this error's code.
func (*NetworkerError) Unwrap ¶
func (e *NetworkerError) Unwrap() error
type NetworkerErrorCode ¶
type NetworkerErrorCode int
NetworkerErrorCode classifies networker errors for programmatic handling.
const ( ErrCodeSessionNotFound NetworkerErrorCode = iota + 1 ErrCodeNoHandlerFound ErrCodeForwarderFailed ErrCodeManagerShuttingDown ErrCodeInvalidStateTransition ErrCodeInvalidConnectionType )
func (NetworkerErrorCode) String ¶
func (c NetworkerErrorCode) String() string
type Plugin ¶
func (*Plugin) GRPCClient ¶
func (p *Plugin) GRPCClient( _ context.Context, _ *plugin.GRPCBroker, c *grpc.ClientConn, ) (interface{}, error)
func (*Plugin) GRPCServer ¶
type PluginClient ¶
type PluginClient struct {
// contains filtered or unexported fields
}
func (*PluginClient) ClosePortForwardSession ¶
func (p *PluginClient) ClosePortForwardSession( ctx *types.PluginContext, sessionID string, ) (*PortForwardSession, error)
func (*PluginClient) FindPortForwardSessions ¶
func (p *PluginClient) FindPortForwardSessions( ctx *types.PluginContext, req FindPortForwardSessionRequest, ) ([]*PortForwardSession, error)
FindPortForwardSessions returns all of the port forward sessions that match the given request.
func (*PluginClient) GetPortForwardSession ¶
func (p *PluginClient) GetPortForwardSession( ctx *types.PluginContext, sessionID string, ) (*PortForwardSession, error)
GetPortForwardSession returns a port forward session by ID.
func (*PluginClient) GetSupportedPortForwardTargets ¶
func (p *PluginClient) GetSupportedPortForwardTargets(ctx *types.PluginContext) ([]string, error)
GetSupportedPortForwardTargets returns the list of targets that are supported by this plugin for port forwarding.
func (*PluginClient) ListPortForwardSessions ¶
func (p *PluginClient) ListPortForwardSessions( ctx *types.PluginContext, ) ([]*PortForwardSession, error)
ListPortForwardSessions returns all of the port forward sessions.
func (*PluginClient) StartPortForwardSession ¶
func (p *PluginClient) StartPortForwardSession( ctx *types.PluginContext, opts PortForwardSessionOptions, ) (*PortForwardSession, error)
func (*PluginClient) StopAll ¶
func (p *PluginClient) StopAll()
StopAll performs a best-effort shutdown of all remote sessions by listing them and closing each individually. Per-session close errors are logged but do not stop the loop.
type PluginOpts ¶
type PluginOpts struct {
// ResourceForwarders maps resource key → ResourceForwarder.
ResourceForwarders map[string]ResourceForwarder
// StaticForwarders maps key → StaticForwarder.
StaticForwarders map[string]StaticForwarder
}
PluginOpts contains the options for the networker plugin, passed to RegisterPlugin.
type PluginServer ¶
type PluginServer struct {
networkerpb.UnimplementedNetworkerPluginServer
Impl Provider
}
func (*PluginServer) ClosePortForwardSession ¶
func (s *PluginServer) ClosePortForwardSession( ctx context.Context, in *networkerpb.PortForwardSessionByIdRequest, ) (*networkerpb.PortForwardSessionByIdResponse, error)
func (*PluginServer) FindPortForwardSessions ¶
func (s *PluginServer) FindPortForwardSessions( ctx context.Context, in *networkerpb.FindPortForwardSessionRequest, ) (*networkerpb.PortForwardSessionListResponse, error)
func (*PluginServer) GetPortForwardSession ¶
func (s *PluginServer) GetPortForwardSession( ctx context.Context, in *networkerpb.PortForwardSessionByIdRequest, ) (*networkerpb.PortForwardSessionByIdResponse, error)
func (*PluginServer) GetSupportedPortForwardTargets ¶
func (s *PluginServer) GetSupportedPortForwardTargets( ctx context.Context, _ *emptypb.Empty, ) (*networkerpb.GetSupportedPortForwardTargetsResponse, error)
func (*PluginServer) ListPortForwardSessions ¶
func (s *PluginServer) ListPortForwardSessions( ctx context.Context, _ *emptypb.Empty, ) (*networkerpb.PortForwardSessionListResponse, error)
func (*PluginServer) StartPortForwardSession ¶
func (s *PluginServer) StartPortForwardSession( ctx context.Context, in *networkerpb.PortForwardSessionOptions, ) (*networkerpb.PortForwardSessionByIdResponse, error)
type PortChecker ¶
type PortChecker interface {
// FindFreePort returns a free TCP port.
FindFreePort() (int32, error)
IsPortUnavailable(port int32) bool
}
PortChecker abstracts port availability operations so tests can inject fakes.
type PortForwardConnectionType ¶
type PortForwardConnectionType string
const ( PortForwardConnectionTypeResource PortForwardConnectionType = "RESOURCE" PortForwardConnectionTypeStatic PortForwardConnectionType = "STATIC" )
type PortForwardProtocol ¶
type PortForwardProtocol string
const ( PortForwardProtocolTCP PortForwardProtocol = "TCP" PortForwardProtocolUDP PortForwardProtocol = "UDP" )
func PortForwardProtocolFromProto ¶
func PortForwardProtocolFromProto( p networkerpb.PortForwardProtocol, ) PortForwardProtocol
PortForwardProtocolFromProto converts from the protobuf enum. Unknown proto values map to an invalid internal protocol (empty string), which callers can detect via Valid().
func (PortForwardProtocol) String ¶
func (p PortForwardProtocol) String() string
func (PortForwardProtocol) ToProto ¶
func (p PortForwardProtocol) ToProto() networkerpb.PortForwardProtocol
ToProto converts to the protobuf enum. Unknown values are encoded as an unknown enum value (-1), so callers should validate with Valid() upstream.
func (PortForwardProtocol) Valid ¶
func (p PortForwardProtocol) Valid() bool
Valid returns true if the protocol is a known value (TCP or UDP).
type PortForwardProvider ¶
type PortForwardProvider interface {
GetSupportedPortForwardTargets(*types.PluginContext) ([]string, error)
GetPortForwardSession(*types.PluginContext, string) (*PortForwardSession, error)
ListPortForwardSessions(*types.PluginContext) ([]*PortForwardSession, error)
FindPortForwardSessions(
*types.PluginContext,
FindPortForwardSessionRequest,
) ([]*PortForwardSession, error)
StartPortForwardSession(
*types.PluginContext,
PortForwardSessionOptions,
) (*PortForwardSession, error)
ClosePortForwardSession(*types.PluginContext, string) (*PortForwardSession, error)
StopAll()
}
type PortForwardResourceConnection ¶
type PortForwardResourceConnection struct {
ResourceData map[string]interface{} `json:"resource_data"`
ConnectionID string `json:"connection_id"`
PluginID string `json:"plugin_id"`
ResourceID string `json:"resource_id"`
ResourceKey string `json:"resource_key"`
}
func PortForwardResourceConnectionFromJson ¶
func PortForwardResourceConnectionFromJson(o map[string]any) *PortForwardResourceConnection
func PortForwardResourceConnectionFromProto ¶
func PortForwardResourceConnectionFromProto( o *networkerpb.PortForwardResourceConnection, ) PortForwardResourceConnection
func (*PortForwardResourceConnection) ToProto ¶
func (c *PortForwardResourceConnection) ToProto() *networkerpb.PortForwardResourceConnection
func (*PortForwardResourceConnection) ToSessionOptionsProto ¶
func (c *PortForwardResourceConnection) ToSessionOptionsProto() *networkerpb.PortForwardSessionOptions_ResourceConnection
func (*PortForwardResourceConnection) ToSessionProto ¶
func (c *PortForwardResourceConnection) ToSessionProto() *networkerpb.PortForwardSession_ResourceConnection
type PortForwardSession ¶
type PortForwardSession struct {
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
Connection Connection `json:"connection"`
Labels map[string]string `json:"labels"`
ID string `json:"id"`
Protocol PortForwardProtocol `json:"protocol"`
State SessionState `json:"state"`
ConnectionType PortForwardConnectionType `json:"connection_type"`
Encryption PortForwardSessionEncryption `json:"encryption"`
LocalPort int32 `json:"local_port"`
RemotePort int32 `json:"remote_port"`
}
PortForwardSession represents a session between a forwarding target and the host.
func NewPortForwardSessionFromProto ¶
func NewPortForwardSessionFromProto(s *networkerpb.PortForwardSession) *PortForwardSession
NewPortForwardSessionFromProto creates a PortForwardSession from a protobuf.
func (*PortForwardSession) ToProto ¶
func (s *PortForwardSession) ToProto() *networkerpb.PortForwardSession
type PortForwardSessionEncryption ¶
type PortForwardSessionEncryption struct {
Algorithm string `json:"algorithm"`
Key string `json:"key"`
Enabled bool `json:"enabled"`
}
func PortForwardSessionEncryptionFromProto ¶
func PortForwardSessionEncryptionFromProto( o *networkerpb.PortForwardSessionEncryption, ) PortForwardSessionEncryption
func (*PortForwardSessionEncryption) ToProto ¶
func (o *PortForwardSessionEncryption) ToProto() *networkerpb.PortForwardSessionEncryption
type PortForwardSessionOptions ¶
type PortForwardSessionOptions struct {
Connection Connection `json:"connection"`
Labels map[string]string `json:"labels"`
Params map[string]string `json:"params"`
Protocol PortForwardProtocol `json:"protocol"`
ConnectionType PortForwardConnectionType `json:"connection_type"`
Encryption PortForwardSessionEncryption `json:"encryption"`
LocalPort int32 `json:"local_port"`
RemotePort int32 `json:"remote_port"`
}
func NewPortForwardSessionOptionsFromProto ¶
func NewPortForwardSessionOptionsFromProto( o *networkerpb.PortForwardSessionOptions, ) *PortForwardSessionOptions
func (*PortForwardSessionOptions) ToProto ¶
func (o *PortForwardSessionOptions) ToProto() *networkerpb.PortForwardSessionOptions
type PortForwardStaticConnection ¶
type PortForwardStaticConnection struct {
Address string `json:"address"`
}
func PortForwardStaticConnectionFromJson ¶
func PortForwardStaticConnectionFromJson(o map[string]any) *PortForwardStaticConnection
func PortForwardStaticConnectionFromProto ¶
func PortForwardStaticConnectionFromProto( o *networkerpb.PortForwardStaticConnection, ) PortForwardStaticConnection
func (*PortForwardStaticConnection) ToProto ¶
func (c *PortForwardStaticConnection) ToProto() *networkerpb.PortForwardStaticConnection
func (*PortForwardStaticConnection) ToSessionOptionsProto ¶
func (c *PortForwardStaticConnection) ToSessionOptionsProto() *networkerpb.PortForwardSessionOptions_StaticConnection
func (*PortForwardStaticConnection) ToSessionProto ¶
func (c *PortForwardStaticConnection) ToSessionProto() *networkerpb.PortForwardSession_StaticConnection
type Provider ¶
type Provider interface {
PortForwardProvider
}
Provider is the interface satisfied by the plugin server and client to provide the networker functionality.
type RealPortChecker ¶
type RealPortChecker struct{}
RealPortChecker performs actual network checks.
func (RealPortChecker) FindFreePort ¶
func (RealPortChecker) FindFreePort() (int32, error)
func (RealPortChecker) IsPortUnavailable ¶
func (RealPortChecker) IsPortUnavailable(port int32) bool
type ResourceForwarder ¶
type ResourceForwarder interface {
ForwardResource(ctx context.Context, pctx *types.PluginContext, opts ResourcePortForwardHandlerOpts) (*ForwarderResult, error)
}
ResourceForwarder initiates a port forward for a resource.
type ResourceForwarderFunc ¶
type ResourceForwarderFunc func(ctx context.Context, pctx *types.PluginContext, opts ResourcePortForwardHandlerOpts) (*ForwarderResult, error)
ResourceForwarderFunc adapts a plain function to the ResourceForwarder interface.
func (ResourceForwarderFunc) ForwardResource ¶
func (f ResourceForwarderFunc) ForwardResource(ctx context.Context, pctx *types.PluginContext, opts ResourcePortForwardHandlerOpts) (*ForwarderResult, error)
type ResourcePortForwardHandlerOpts ¶
type ResourcePortForwardHandlerOpts struct {
Resource PortForwardResourceConnection `json:"resource"`
Options PortForwardSessionOptions `json:"options"`
}
type SessionState ¶
type SessionState string
const ( SessionStateActive SessionState = "ACTIVE" SessionStatePaused SessionState = "PAUSED" SessionStateStopped SessionState = "STOPPED" SessionStateFailed SessionState = "FAILED" )
func (SessionState) String ¶
func (s SessionState) String() string
func (SessionState) ToProto ¶
func (s SessionState) ToProto() networkerpb.PortForwardSession_SessionState
type StaticForwarder ¶
type StaticForwarder interface {
ForwardStatic(ctx context.Context, pctx *types.PluginContext, opts StaticPortForwardHandlerOpts) (*ForwarderResult, error)
}
StaticForwarder initiates a port forward for a static address.
type StaticForwarderFunc ¶
type StaticForwarderFunc func(ctx context.Context, pctx *types.PluginContext, opts StaticPortForwardHandlerOpts) (*ForwarderResult, error)
StaticForwarderFunc adapts a plain function to the StaticForwarder interface.
func (StaticForwarderFunc) ForwardStatic ¶
func (f StaticForwarderFunc) ForwardStatic(ctx context.Context, pctx *types.PluginContext, opts StaticPortForwardHandlerOpts) (*ForwarderResult, error)
type StaticPortForwardHandlerOpts ¶
type StaticPortForwardHandlerOpts struct {
Static PortForwardStaticConnection `json:"static"`
Options PortForwardSessionOptions `json:"options"`
}