relay/session.go at main · ctrlplanedev/relay · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
package relay

import "context"

// -----------------------------------------------------------------------------
// Session Interfaces
// -----------------------------------------------------------------------------

// Session represents an active session between a client and an agent.
// Sessions are bidirectional communication channels for PTY, TCP tunnels, etc.
type Session interface {
	// ID returns the unique session identifier.
	ID() SessionID

	// Type returns the session type (pty, tunnel:tcp, tunnel:udp).
	Type() SessionType

	// AgentID returns the ID of the agent handling this session.
	AgentID() AgentID

	// ClientID returns the ID of the client that owns this session.
	ClientID() ClientID

	// Write sends input data to the session (client → agent).
	Write(ctx context.Context, data []byte) error

	// DeliverOutput sends output data to the client (agent → client).
	// This looks up the client via the ClientRegistry, enabling distributed routing.
	DeliverOutput(ctx context.Context, data []byte) error

	// NotifyClose sends a close notification to the client.
	NotifyClose(ctx context.Context) error

	// SetOnClose sets a callback invoked when the session closes.
	// Used by the Hub to track session lifecycle.
	SetOnClose(callback func())

	// Close terminates the session.
	Close(ctx context.Context) error

	// Resize sends a terminal resize event to the PTY.
	// Returns an error if this is not a PTY session.
	Resize(ctx context.Context, rows, cols uint16) error
}

// -----------------------------------------------------------------------------
// Session Options
// -----------------------------------------------------------------------------

// SessionOptions contains options for opening a new session.
// Different session types use different option fields.
type SessionOptions struct {
	// PTY contains options specific to PTY sessions.
	PTY *PTYOptions `json:"pty,omitempty"`

	// Tunnel contains options for TCP/UDP tunnel sessions.
	Tunnel *TunnelOptions `json:"tunnel,omitempty"`

	// Extra contains additional key-value options for extensibility.
	Extra map[string]any `json:"extra,omitempty"`
}

// PTYOptions contains options for PTY sessions.
type PTYOptions struct {
	// Shell is the shell to execute (defaults to $SHELL or /bin/sh).
	Shell string `json:"shell,omitempty"`

	// Args are arguments to pass to the shell.
	Args []string `json:"args,omitempty"`

	// WorkingDir is the initial working directory.
	WorkingDir string `json:"working_dir,omitempty"`

	// Env are additional environment variables to set.
	Env map[string]string `json:"env,omitempty"`

	// Rows is the initial terminal height.
	Rows uint16 `json:"rows,omitempty"`

	// Cols is the initial terminal width.
	Cols uint16 `json:"cols,omitempty"`
}

// TunnelOptions contains options for TCP/UDP tunnel sessions.
type TunnelOptions struct {
	// TargetHost is the destination host to connect to.
	TargetHost string `json:"target_host"`

	// TargetPort is the destination port to connect to.
	TargetPort uint16 `json:"target_port"`
}