appserverproxy

Documentation

Overview

Package appserverproxy exposes one initialized Codex app-server connection to a stock Codex TUI without making the TUI a second upstream subscriber.

Index

• Variables
• type AfterRequest
• type BeforeRequest
• type LocalRequest
• type Options
• type Proxy
  • func Listen(parent context.Context, opts Options) (*Proxy, error)
  • func (p *Proxy) Attached() bool
  • func (p *Proxy) Close() error
  • func (p *Proxy) Done() <-chan struct{}
  • func (p *Proxy) Endpoint() string
  • func (p *Proxy) ForwardReverse(ctx context.Context, request *appserver.ReverseRequest) (bool, error)
  • func (p *Proxy) Notify(notification appserver.Notification)
• type Upstream

Variables

var (
	ErrClosed          = errors.New("appserver proxy: closed")
	ErrNoAttachedTUI   = errors.New("appserver proxy: no attached TUI")
	ErrTUIBusy         = errors.New("appserver proxy: a TUI is already connected")
	ErrUnknownResponse = errors.New("appserver proxy: unknown TUI response id")
)

Types

type AfterRequest

type AfterRequest func(method string, state any, result json.RawMessage, err error)

AfterRequest observes the terminal result of a forwarded TUI request. Implementations must return promptly.

type BeforeRequest

type BeforeRequest func(method string, params json.RawMessage) (rewritten json.RawMessage, state any, rpcErr *appserver.RPCError)

BeforeRequest validates or rewrites a TUI request before it is sent to the upstream app-server. State is passed to AfterRequest even when the upstream request fails.

type LocalRequest

type LocalRequest func(method string, params json.RawMessage, state any) (result json.RawMessage, handled bool, err error)

LocalRequest may terminate a rewritten TUI request without sending it to the upstream app-server. An error is meaningful only when handled is true. Implementations must return promptly.

type Options

type Options struct {
	Endpoint               string
	Upstream               Upstream
	InitializeResponse     appserver.InitializeResponse
	ExpectedClientVersion  string
	MaxMessageSize         int64
	MaxConcurrentCalls     int
	WriteQueueSize         int
	HandshakeTimeout       time.Duration
	WriteTimeout           time.Duration
	RequestTimeout         time.Duration
	TurnStartTimeout       time.Duration
	ReverseResponseTimeout time.Duration
	BeforeRequest          BeforeRequest
	LocalRequest           LocalRequest
	AfterRequest           AfterRequest
	OnAttach               func()
	OnDetach               func()
	Logger                 *slog.Logger
}

Options configures one proxy listener.

type Proxy

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

Proxy owns a Unix HTTP/WebSocket listener and at most one downstream TUI.

func Listen

func Listen(parent context.Context, opts Options) (*Proxy, error)

Listen creates the Unix socket and starts accepting stock Codex TUI WebSocket connections. The socket is created with mode 0600.

func (*Proxy) Attached

func (p *Proxy) Attached() bool

Attached reports whether a TUI completed initialize and thread/resume.

func (*Proxy) Close

func (p *Proxy) Close() error

Close stops the listener, disconnects the TUI, and removes the socket.

func (*Proxy) Done

func (p *Proxy) Done() <-chan struct{}

Done closes after the listener and any attached TUI have stopped.

func (*Proxy) Endpoint

func (p *Proxy) Endpoint() string

Endpoint returns the configured downstream Unix endpoint.

func (*Proxy) ForwardReverse

func (p *Proxy) ForwardReverse(ctx context.Context, request *appserver.ReverseRequest) (bool, error)

ForwardReverse sends one app-server reverse request to the attached TUI and relays its result to upstream. It returns false without answering request when no ready TUI exists or the TUI disconnects before answering, allowing the caller to apply its headless fallback policy.

func (*Proxy) Notify

func (p *Proxy) Notify(notification appserver.Notification)

Notify forwards an upstream app-server notification without blocking the upstream ordered reader. A slow TUI is disconnected when its bounded write queue fills; the Intercom service remains alive.

type Upstream

type Upstream interface {
	StartCall(context.Context, string, any) (*appserver.PendingCall, error)
	Notify(context.Context, string, any) error
}

Upstream is the raw request surface needed to multiplex a downstream TUI over Intercom's one initialized app-server connection.