xref: /xsrc/external/mit/xorgproto/dist/PM_spec

			 Proxy Management Protocol
			     Draft Version 1.0
			  Ralph Mor, X Consortium


The Proxy Management Protocol is an ICE based protocol that provides a way
for application servers to easily locate proxy services available to them.

Typically, a service called a "proxy manager" is responsible for resolving
requests for proxy services, starting new proxies when appropriate, and
keeping track of all of the available proxy services.  The proxy manager
strives to reuse existing proxies whenever possible.

In order to request a proxy service, the GET_PROXY_ADDR message is sent to
the proxy manager.  The proxy manager will in turn forward this message to
a proxy that it thinks can satisfy the request.

GET_PROXY_ADDR
  proxy-service  : STRING
  server-address : STRING
  host-address   : STRING
  options	 : STRING
  auth-data-len	 : CARD16
  auth-name	 : STRING or None
  auth-data	 : LISTofCARD8 or None

  -->

  status	 : CARD8
  proxy-address  : STRING
  failure-reason : STRING


proxy-service is the name of the proxy service to be requested, for example
"LBX".  proxy-service is a case insensitive string.

server-address is the network address of the target server.  The format of
the address is specific to proxy-service.  For example, for a proxy service
of "LBX", the address would be an X display address (e.g, "wkstn.x.org:0").

host-address is the network address of the host on which the proxied
application will run.  This information might be used by the proxy to
restrict access to a specific host.

options are proxy specific options that will be passed to the proxy.  The
details of these options are not specified here.  Their syntax and
semantics are defined by each proxy service.

If auth-data-len is nonzero, then auth-name and auth-data contain
authentication or authorization information that should be passed to
the proxy.  The proxy will typically use this to authenticate and
authorize itself to the target server.  The details of how the
auth fields are used are specific to each proxy service.


After sending GET_PROXY_ADDR the proxy manager expects a reply from
the proxy. The status field of the reply indicates if the request can
be satisfied.

If status is Success, proxy-address will contain the network address of the
proxy willing to handle this request.  The format of the proxy address is
specific to the proxy service being used.  For example, for a proxy service
of "LBX", the proxy address would be the X display address of the proxy
(e.g, "gateway.x.org:63").  The proxy manager will forward the successful
GET_PROXY_ADDR reply to whomever requested the proxy service.

If status is Unable, the proxy is not able to satisfy the request but
it believes some other proxy might be able to do so.  Proxy-address is
the empty string and failure-reason indicates the reason for failure.
The proxy manager may choose to forward the original GET_PROXY_ADDR to
another already running proxy, or it may choose to start up a new
proxy.  In the event that the proxy manager can not find or start a
proxy, it will send a GET_PROXY_ADDR reply (with status Failure and an
appropriate failure-reason) to whomever requested the proxy service.

If status is Failure, the proxy is not able to satisfy the request and
in addition is informing the requester that the request is invalid in
some way and should not be retried.


If the proxy manager starts up a new proxy, the proxy manager will
need an indication from the proxy that it is ready to accept
requests.  The proxy is required to send a START_PROXY message to the
proxy manager to identify itself and signal its readiness to receive
requests.

START_PROXY
  proxy-service  : STRING   (name of proxy service, e.g. "LBX")


When the proxy manager receives the START_PROXY message from the
proxy it checks that the proxy-service is the one that it's expecting.
If the proxy-service is incorrect, an IceBadValue error will be sent
to the proxy.  Otherwise, the proxy manager will forward the original
GET_PROXY_ADDR request to the proxy and the proxy will respond to the
GET_PROXY_ADDR request in the same way as discussed above.


Protocol
--------

ICE protocol name is "PROXY_MANAGEMENT".
The major opcode is assigned at run-time by ICE.


Types
-----

STRING
  2  CARD16	  length
  n  LISTofCARD8  the string
  p		  p = pad(2+n,8)



Encoding
--------

GET_PROXY_ADDR

  1  ?			PROXY_MANAGEMENT
  1  1			opcode
  2  n			auth-data-len (in bytes)
  4  (a+b+c+d+e+n+p)/8	length of remaining data in 8-byte units
  a  STRING		proxy-service
  b  STRING		server-address
  c  STRING		host-address
  d  STRING		options
  e  STRING		auth-name (if auth-data-len > 0)
  n  LISTofCARD8	auth-data (if auth-data-len > 0)
  p			unused, p=pad(n,8)

GET_PROXY_ADDR_REPLY

  1  ?			PROXY_MANAGEMENT
  1  2			opcode
  1  CARD8		status
                          0	Unable
			  1	Success
			  2	Failure
  1			unused
  4  (a+b)/8		length of remaining data in 8-byte units
  a  STRING		proxy-address
  b  STRING		failure-reason


START_PROXY

  1  ?			PROXY_MANAGEMENT
  1  3			opcode
  2			unused
  4  a/8		length of remaining data in 8-byte units
  a  STRING		proxy-service