networker

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Mar 6, 2026 License: AGPL-3.0 Imports: 24 Imported by: 2

Documentation

Index

Constants

View Source
const (
	PluginID = "networker"
)

Variables

View Source
var (
	ErrNetSessionNotFound        = &NetworkerError{Code: ErrCodeSessionNotFound}
	ErrNetNoHandlerFound         = &NetworkerError{Code: ErrCodeNoHandlerFound}
	ErrNetPortUnavailable        = &NetworkerError{Code: ErrCodePortUnavailable}
	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

func FindFreeTCPPort() (int32, error)

FindFreeTCPPort finds an available port by letting the OS pick a free port.

func IsPortUnavailable

func IsPortUnavailable(port int32) bool

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 (FindPortForwardSessionRequest) ToProto

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)

func (*Manager) StopAll

func (m *Manager) StopAll()

StopAll cancels all active sessions and waits for monitor goroutines to complete within the configured timeout.

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
	ErrCodePortUnavailable
	ErrCodeForwarderFailed
	ErrCodeManagerShuttingDown
	ErrCodeInvalidStateTransition
	ErrCodeInvalidConnectionType
)

func (NetworkerErrorCode) String

func (c NetworkerErrorCode) String() string

type Plugin

type Plugin struct {
	plugin.Plugin
	Impl Provider
}

func (*Plugin) GRPCClient

func (p *Plugin) GRPCClient(
	_ context.Context,
	_ *plugin.GRPCBroker,
	c *grpc.ClientConn,
) (interface{}, error)

func (*Plugin) GRPCServer

func (p *Plugin) GRPCServer(_ *plugin.GRPCBroker, s *grpc.Server) error

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 PortChecker

type PortChecker interface {
	// FindFreePort returns a free TCP port.
	FindFreePort() (int32, error)
	// IsPortUnavailable returns true if the port is already in use.
	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

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 (*PortForwardResourceConnection) ToProto

func (*PortForwardResourceConnection) ToSessionOptionsProto

func (*PortForwardResourceConnection) ToSessionProto

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

type PortForwardSessionEncryption

type PortForwardSessionEncryption struct {
	Algorithm string `json:"algorithm"`
	Key       string `json:"key"`
	Enabled   bool   `json:"enabled"`
}

func (*PortForwardSessionEncryption) ToProto

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 (*PortForwardSessionOptions) ToProto

type PortForwardStaticConnection

type PortForwardStaticConnection struct {
	Address string `json:"address"`
}

func PortForwardStaticConnectionFromJson

func PortForwardStaticConnectionFromJson(o map[string]any) *PortForwardStaticConnection

func (*PortForwardStaticConnection) ToProto

func (*PortForwardStaticConnection) ToSessionOptionsProto

func (*PortForwardStaticConnection) ToSessionProto

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

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

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

type StaticPortForwardHandlerOpts

type StaticPortForwardHandlerOpts struct {
	Static  PortForwardStaticConnection `json:"static"`
	Options PortForwardSessionOptions   `json:"options"`
}

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL