Documentation
¶
Overview ¶
Package proxy carries bus messages between two processes over a WebSocket.
A worker in one process and a worker in another cannot see each other's bus. A pair of proxies joins them: each sits on its own bus as an ordinary worker, forwards the messages meant for the far side, and puts what arrives from there onto its own bus. Neither worker knows the other is remote.
The pair is a client and a server because one of them has to dial. The difference is only how the socket is obtained and which way the routing rules point; what travels, and how, is the same either way.
Which messages cross is deliberately narrow. A message addressed to the worker on the far side crosses, and nothing else does, so a bus carrying a conversation's whole traffic does not put all of it on the wire. Message types named in ForwardMessages cross as well, addressed or not, which is how frames reach a bridged worker in another process.
Index ¶
Constants ¶
const ( EventConnected = "on_connected" EventDisconnected = "on_disconnected" )
EventConnected fires once the client has opened its connection to the server. EventDisconnected fires when that connection ends.
Neither carries an argument: the proxy raising it is the source, and the socket behind it belongs to the proxy.
const ( EventClientConnected = "on_client_connected" EventClientDisconnected = "on_client_disconnected" )
EventClientConnected fires once the server proxy is ready to carry messages for the client that connected. EventClientDisconnected fires when that client goes.
Neither carries an argument: the proxy raising it is the source, and the socket behind it belongs to the proxy.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
Client forwards bus messages to a worker in another process, over a connection it opens itself.
It is an ordinary worker on this bus. A message addressed to the worker named by RemoteWorker crosses; what arrives addressed to LocalWorker is put on this bus. Neither worker knows the other is remote.
It starts inactive unless told otherwise, so nothing dials until something decides it should.
func (*Client) OnActivated ¶
OnActivated opens the connection and starts reading from it.
func (*Client) OnBusMessage ¶
OnBusMessage forwards what is meant for the far side.
A message addressed to the remote worker crosses. A message of a forwarded type crosses only when this side's own worker sent it, which is what keeps a frame from being echoed back to the process it came from.
type ClientConfig ¶
type ClientConfig struct {
// Name is what other workers on this bus address the proxy by.
Name string
// URL is the server proxy's WebSocket endpoint.
URL string
// RemoteWorker is the name of the worker on the far side. A message
// addressed to it is what crosses, and nothing else is.
RemoteWorker string
// LocalWorker is the name of the worker on this side that answers. Only a
// message arriving addressed to it is put on this bus; anything else is
// dropped, since it was not this process's to act on.
LocalWorker string
// ForwardMessages are message types that cross whoever they are addressed
// to, given as sample values (&bus.FrameMessage{}). It is how frames reach a
// bridged worker in another process. Outbound, only the ones this side's
// worker sent cross.
ForwardMessages []bus.Message
// Headers are sent with the WebSocket handshake, which is where a proxy that
// has to authenticate does it.
Headers map[string]string
// Serializer converts messages to bytes and back; nil uses the JSON one.
Serializer bus.MessageSerializer
// Active reports whether the proxy connects as soon as it starts. Nil leaves
// it inactive, because connecting is almost always something another event
// decides: a client arriving, a call beginning. Activate it to connect.
Active *bool
}
ClientConfig configures a Client.
type Server ¶
Server carries bus messages for a worker in another process, over a connection that process opened.
It is the far half of a Client: the same traffic, the same rules, and the socket arriving rather than being dialed. Build one per accepted connection, from the endpoint that upgraded the request, and add it to the runner.
It also tells the client when the local worker becomes ready, so the client's side learns that the worker it is addressing exists.
func NewServer ¶
func NewServer(cfg ServerConfig) *Server
NewServer builds a server proxy over an accepted connection.
func (*Server) OnBusMessage ¶
OnBusMessage forwards what the local worker sends to the client.
Only the local worker's own messages cross: this side may carry the traffic of several workers and the client has no business seeing the rest. Of those, a message addressed to the remote worker crosses, as does one of a forwarded type whatever it is addressed to.
func (*Server) OnWorkerReady ¶
func (s *Server) OnWorkerReady(ctx context.Context, data registry.WorkerReadyData)
OnWorkerReady tells the client that the local worker exists and can be addressed. Without it the client's side would be sending to a name it has no reason to believe in.
type ServerConfig ¶
type ServerConfig struct {
// Name is what other workers on this bus address the proxy by.
Name string
// Conn is the accepted WebSocket connection to the client, which the
// endpoint upgrading the request hands over.
Conn *wsutil.Conn
// LocalWorker is the name of the worker on this side. Only what it sends
// crosses, and only what arrives addressed to it is put on this bus.
LocalWorker string
// RemoteWorker is the name of the worker on the client. A message addressed
// to it is what crosses.
RemoteWorker string
// ForwardMessages are message types that cross whoever they are addressed
// to, given as sample values (&bus.FrameMessage{}). It is how frames reach a
// bridged worker in another process. Outbound, only the ones the local
// worker sent cross.
ForwardMessages []bus.Message
// Serializer converts messages to bytes and back; nil uses the JSON one.
Serializer bus.MessageSerializer
}
ServerConfig configures a Server.
Source Files