Persistent Outbound Connections

The client initiates a persistent connection to a server by registering as described in the draft RFC, passing +sip.instance and reg-id parameters in the Contact header of the REGISTER request.

The instance parameter must uniquely identify this user agent, and must be persistent across reboots. It is up to the user agent to derive this instance identifier. The draft RFC recommends using a UUID.

The reg-id parameter is an integer, and identifies the connection to a particular endpoint. If the client wishes to initiate more than one persistent connection to the same host, each REGISTER request must specify a different reg-id. An example REGISTER message is shown below:

When the client attempts to send a REGISTER in this way, the SIP RA detects that a new persistent connection is required, and opens a connection to the server. If a successful response is received, then the stack marks the connection as persistent, and will automatically perform the heartbeat and reconnection procedures specified by the draft RFC. If the registration response is not successful, or times out, an alarm is raised and the RA will initiate the reconnection procedures, and will try to reconnect and register again.

To send requests on the connection, the client only has to ensure that the request is routed to the same server that handled the REGISTER. This can be achieved by inserting a Route header in any request. For example, if the client had registered as above, it would use the Route header:

If the RA sees that a request is destined for a server that it already has a persistent connection for, then it will send the request on that connection. If there are several persistent connections open to the server, then the most recently created one is used, as specified by the draft RFC.

If a persistent connection has gone down, the RA will automatically attempt to reconnect at intervals defined in the RFC (normally starting at 30 seconds). If a client tries to send a request on the connection and it is not currently available, then a SipException will be thrown.

The RA will automatically re-register in the case of a connection failure, but the application is still responsible for re-registering before the previous registration expires. When the initial registration response is received, the Contact header will contain an expires parameter specifying the lifetime of the registration, in seconds. The application must set the appropriate timers so that it re-registers before the registration is due to expire.

After establishing a persistent connection as above, an SBB client may attach to a PersistentOutboundConnection activity to be notified when the underlying connection goes up and down.

The RA uses the STUN heartbeat mechanism to check that the server is still responding, and also to check if the NAT mapping has changed. If a persistent connection is idle for 90 seconds, a STUN bind request is sent. If no response is received, or if the response indicated that the NAT mapping has changed, then the RA will automatically close the connection and begin reconnection procedures. No application involvement is required for handling the STUN messages, this is done entirely by the RA.

Tearing down a persistent connection is done by sending an unregister request. This is a REGISTER request as above, but with an expires value of zero. When this request is sent on a persistent connection, the RA knows it can close the connection, and it does not begin reconnection procedures, and no alarm is raised.

If the unregister request is sent when the connection is already down, the RA will treat this as a signal that the connection should be closed permanently and no more reconnection attempts will be made. Any alarms associated with the connection are cleared. The RA will pass an OK response back up to the application.

An example service is included which creates and tears down a persistent connection, using the REGISTER procedures above.

The service will attempt to register when it is activated. The server it tries to register with is specified in the sip.properties variable PERSISTENT_REGISTRAR_URI. By default this is localhost:5080, but should be changed to the URI of another SLEE running the example registrar service.

The alarm types are:

The SIP RA uses a proprietary header, X-Flow-ID, to indicate to the server the applications whose incoming "flow" (connection) a request was received on. The header contains a string token which uniquely identifies an incoming flow on this server. The header is only set on incoming requests when the request is received on an existing persistent incoming flow, or it is an initial REGISTER request which is creating a new incoming flow.

Similarly, if an application wants to send a request on a particular incoming flow, it can set the X-Flow-ID header in the request before sending it. The RA will see the header and attempt to send on the flow indicated by the Flow-ID, throwing an exception if the flow is not present.

The RA will always remove the X-Flow-ID header before the request is sent on the network.

Registrar applications must check incoming REGISTERs to see if the X-Flow-ID header is present, and if so, save the Flow-ID along with the other registration details. This is so that a proxy application can look up the registration and route requests to the correct flow.

The example RegistrarSbb has been updated to save the flow, along with the other registration details.

Proxy applications must be prepared to route requests to particular flows. When a proxy looks up a user’s registration details, it can get the Flow-ID (if present), and insert an X-Flow-ID header so the RA will send the request on the correct flow.

If the proxy is a record-routing proxy, meaning that it will see all requests in a dialog, then the proxy must take care to record-route correctly so that subsequent requests in the dialog will be sent on the correct flow. The draft RFC is not specific about how this is done, but one procedure that works is the "double record-route".

When processing an initial request, the proxy must check if the request was received on an incoming flow, or is destined for an incoming flow. If either is true, the proxy inserts two Record-Route headers. Each header may contain a Flow-ID. Later, when one of the parties in the dialog sends a subsequent request, it will arrive at the proxy with two Route headers, denoting the incoming and/or outgoing flows. The proxy removes both Route headers, and sends the request out on the flow specified in the second Route header.

The server may forcibly close a persistent incoming connection at any time, by using the proprietary API call OCSleeSipProvider.closeInboundFlow(). This method takes a string parameter, which is the value of the X-Flow-ID header, received with all requests on the connection.

If the connection is closed by the client or is dropped for any reason, other than a call to closeInboundFlow() as above, the server’s RA will generate an un-REGISTER request and pass this up to the SLEE, so that registrar applications can remove the registration associated with that connection. The request will contain the correct address-of-record, contact address, instance-id, and reg-id for the connection, and will have an "expires" value of zero. The response to this request is handled internally, and will not be transmitted over the network.

Note that if the client unregisters normally and closes the connection, the stack will still generate this request, but this will have no effect since the registration would have already been removed.

If the connection is closed by the server using closeInboundFlow(), the un-REGISTER request is not generated, it is assumed that the application will be responsible for cleaning up registration state for that connection.