© Copyright International Business Machines
Corporation 2004, 2005. All rights reserved.
This document is available under the W3C Document License. See the W3C Intellectual Rights Notice and Legal Disclaimers for additional information.
This specification defines a mechanism to deliver messages destined to an unreachable endpoint by allowing the destination to 'poll' the source for messages targeted for it.
This section describes the status of this document at the time of its publication. Other documents may supersede this document.
By publishing this document, W3C acknowledges that IBM has made a formal submission to W3C for discussion. Publication of this document by W3C indicates no endorsement of its content by W3C, nor that W3C has, is, or will be allocating any resources to the issues addressed by it. This document is not the product of a chartered W3C group, but is published as potential input to the W3C Process. Publication of acknowledged Member Submissions at the W3C site is one of the benefits of W3C Membership. Please consult the requirements associated with Member Submissions of section 3.3 of the W3C Patent Policy. Please consult the complete list of acknowledged W3C Member Submissions.
This specification is an initial public draft release and is provided for review and evaluation only. The authors hope to solicit your contributions and suggestions in the near future. The authors make no warrantees or representations regarding the specifications in any manner whatsoever.
When sending SOAP messages in an environment where the two endpoints (source and destination) are not able to freely open connection in both directions, delivery of asynchronous messages becomes problematic. Perhaps the most common scenario being where the initiator (client) of a Web service call is behind a firewall so any messages initiated from the service back to the client can not be delivered. Another common case is where the client does not have a SOAP listener (i.e. server) running to receive asynchronous messages.
In both of these cases, in order for the service to deliver a message to the "unreachable" client endpoint it becomes necessary for the client to initiate the connection, thus allowing the message to be sent back on the response flow of the connection.
This specification defines a mechanism through which an endpoint may initiate a connection to another endpoint for the purposes of allowing messages from the destination/service endpoint to be delivered back to the source/client.
This specification intends to meet the following requirements:
By using the XML, SOAP [SOAP 1.1, SOAP 1.2], and WSDL [WSDL 1.1] extensibility models, the Web service specifications (WS-*) are designed to be composed with each other to provide a rich set of tools to provide security in the Web services environment. This specification specifically relies on other Web service specifications to provide secure, reliable, and/or transacted message delivery and to express Web service and client policy.
This section specifies the notations, namespaces, and terminology used in this specification.
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC 2119].
This specification uses the following syntax to define normative outlines for messages:
The XML Namespace URI that MUST be used by implementations of this specification is:
Table 3 lists XML namespaces that are used in this specification. The choice of any namespace prefix is arbitrary and not semantically significant.
Table 3: Prefixes and XML Namespaces used in this specification.
||(Either SOAP 1.1 or 1.2)||(Either SOAP 1.1 or 1.2)|
||SOAP 1.1 [SOAP 1.1]|
||SOAP 1.2 [SOAP 1.2]|
||WSDL [WSDL 1.1]|
||XML Schema [Part 1, 2]|
An implementation is not compliant with this specification if it fails to satisfy one or more of the MUST or REQUIRED level requirements defined herein. A SOAP Node MUST NOT use the XML Namespace identifier for this specification (listed in Section 2.2) within SOAP Envelopes unless it is compliant with this specification.
To request a message from an endpoint, a requestor MAY send a GetMessage request message to the endpoint. The normative outline for a GetMessage request is:
<s:Envelope ...> <s:Header ...> <wsa:Action> http://www.w3.org/2005/08/ws-polling/GetMessage </wsa:Action> <wsa:MessageID>xs:anyURI</wsa:MessageID> <wsa:ReplyTo>endpoint-reference</wsa:ReplyTo> <wsa:To>xs:anyURI</wsa:To> ... </s:Header> <s:Body ...> <wsp:GetMessage ...> <wsa:MessageID>xs:anyURI</wsa:MessageID> ? <wsp:To>endpoint-reference</wsp:To> ? <wsp:extensions> ... </wsp:extensions> ? </wsp:GetMessage> </s:Body> </s:Envelope>
The following describes normative constraints on the outline listed above:
Upon receipt of this message, the destination will locate any outgoing message that matches the search criteria. The search criteria MUST include examination of the child elements inside the wsp:GetMessage element. When those optional elements are not present the search algorithm MUST at least include partial examination of the wsa:ReplyTo header and MAY also include the wsa:To header (see Searching For Messages, below).
If a message is found that matches the search criteria then it is sent to the endpoint as specified by the WS-Addressing specification (i.e. to the wsa:ReplyTo EPR). A wsa:RelatesTo header MUST be included in the response message that includes the wsa:MessageID from the GetMessage request message, even if one is already present. The normative outline for the response is:
<s:Envelope ...> <s:Header ...> <wsa:Action>...</wsa:Action> <wsa:MessageID>xs:anyURI</wsa:MessageID> <wsa:RelatesTo>xs:anyURI</wsa:RelatesTo> ? <wsa:RelatesTo>messageID from GetMessage</wsa:RelatesTo> <wsa:To>...</wsa:To> ... </s:Header> <s:Body ...> ... </s:Body> </s:Envelope>
The following describes normative constraints on the outline listed above:
If no message is found that matches the search criteria then the NoMessageAvailable message is sent to the endpoint as specified in the wsa:ReplyTo EPR. The normative outline for a NoMessageAvailable response is:
<s:Envelope ...> <s:Header ...> <wsa:Action> http://www.w3.org/2005/08/ws-polling/NoMessageAvailable </wsa:Action> <wsa:MessageID>xs:anyURI</wsa:MessageID> <wsa:RelatesTo>messageID from GetMessage</wsa:RelatesTo> <wsa:To>xs:anyURI</wsa:To> ... </s:Header> <s:Body ...> <wsp:NoMessageAvailable reason="..."? /> </s:Body> </s:Envelope>
The following describes normative constraints on the outline listed above:
When a destination is searching for a message to return to the requestor all of the child elements under the wsp:GetMessage element MUST be used (i.e. a logical AND of the search criteria). It is strongly RECOMMENDED that reference properties be included in EPRs to help uniquely identify messages targeted for a particular endpoint.
A destination MAY choose to include other search criteria. For example, a service endpoint MAY choose to also compare the wsa:To header of the GetMessage request and only locate response messages that were generated from a particular service. Note: see the security section for taking into account the security context when searching.
If more than one message is available the destination is free to use whatever algorithm it deems appropriate for choosing which message to return. For example, a FIFO algorithm may be the best choice but it is not required.
WS-Polling defines a special URI that is similar to the anonymous URI defined by WS-Addressing, meaning the client is unable to offer an endpoint for responses:
Use of this URI in the wsa:ReplyTo EPR of a request message will indicate to the service that the client will use WS-Polling to retrieve the response if the response does not come back through some other means (such as the HTTP response flow). When the service receives a request containing this URI in the wsa:RepyTo EPR it can immediately return an HTTP response code of 202 back to the client - with the assumption that the client will poll for the response at some later point in time. However, the service is not required to return immediately if it chooses not to.
One use of this URI would be to allow the client to indicate to the server that it believes the request will be a long running request and therefore the server is free to return immediately with the assurance that the response will be retrieved later.
Unlike the use of a Mailbox (see section 5) where the service does not need to be aware of WS-Polling at all, in order to use this special URL the client must know the service supports WS-Polling. It is assumed that through examination of the WSDL, WS-Policy or some other out of band means, the client can determine whether or not the service supports it (e.g. GetMessage is in the service's PortType). The server's acceptance of this URI in the wsa:ReplyTo indicates that it not only supports WS-Polling but an understanding that the client is responsible for polling for the response if the service chooses to not send the response message back on the original connection.
Use of the “Hold It” URL places a burden on the service endpoint. It must be able to "hold-on" to the outgoing messages until the receiver of those messages "polls" for them. For some endpoints this may be problematic. A solution for this would follow the same pattern used in email communications - a SOAP Mailbox. When the "anonymous", or "unreachable", side of the communications sends a message it can use a reachable endpoint (the SOAP Mailbox) as its wsa:ReplyTo EPR - thus allowing the service endpoint to deliver any subsequent messages without the need to persist them in any way.
The original endpoint can now "poll" the Mailbox for messages destined for it. This is akin to a simple mail client polling a POP3 server for email. This shifts the burden of managing potentially large number of messages to an endpoint that is dedicated for that purpose.
Setup and logistics of how to create and manage a SOAP Mailbox is out of scope of this document, however, it will probably follow the same pattern that ISPs currently provide. A user (in this case the user of a SOAP client) will register with a SOAP Mailbox provider, which in turn will provide the SOAP client with the appropriate service-URL/EPR to use in its WS-Addressing EPRs.
Since the wsa:To address of the messages in the Mailbox will contain the Mailbox's endpoint address, the GetMessage's Body wsp:To value will not match it. To solve this problem, WS-Polling defines a new element that is meant to be used as a reference property in EPRs:
<wsp:To> URI of client </wsp:To>
This element should be used as a reference property in the client's wsa:ReplyTo EPR so that upon receipt of a message the Mailbox will use the value in this element/header as the true wsa:To value. In other words, the Mailbox is responsible for using the wsp:To value, when present, instead of the wsa:To value when searching for messages to return. The initiator of the GetMessage request is then responsible for either using the wsp:To value instead of the wsa:To value when dispatching the message, or for replacing the wsa:To with the wsp:To prior to dispatching - this decision is out of scope of this document.
Note: if the client chooses to use the WS-Addressing anonymous URI in the wsp:To element, then some reference properties SHOULD be specified to help uniquely identify the destination of the messages.
WS-Polling defines some SOAP headers that can be included in normal message flows that will enable a more optimized polling scheme.
The StatusRequested header can be used to indicate that the sender of the message wishes to query for the existence of any messages on the target endpoint that are waiting to be retrieved via a WS-Polling GetMessage request. The normative outline for a StatusRequested header is:
<wsp:StatusRequested ...> <wsa:MessageID>xs:anyURI</wsa:MessageID> ? <wsp:To>endpoint-reference</wsp:To> ? <wsp:extensions> ... </wsp:extensions> ? </wsp:StatusRequested>
The following describes the content model of the StatusRequested header
As with the GetMessage element, when the optional children elements are not present the search algorithm MUST at least include partial examination of the wsa:ReplyTo header and MAY also include the wsa:To header.
Upon receipt of a StatusRequest header, the receiving endpoint is expected to include a Status header in the response message - if one is generated. The Status header can be used to indicate whether or not there are messages ready to be delivered that satisfy the search criteria in the StatusRequested header. The normative outline for a StatusRequested header is:
<wsp:Status messagesPending="true|false" ...> <wsa:MessageID>xs:anyURI</wsa:MessageID> ? <wsp:To>endpoint-reference</wsp:To> ? <wsp:extensions> ... </wsp:extensions> ? </wsp:Status>
The following describes the content model of the Status header
The Status header can be included on any message that is targeted to the correct WS-Polling client - it is not limited to being sent only when a StatusRequested header was included on a request message. For example, an endpoint may choose to include a Status header on the result of a GetMessage request as a means for the WS-Polling client to know if it should immediately poll for more messages.
This section gives a brief overview of some use-cases that were the driving forces behind this specification. They are not intended to limit the use of this specification but rather give insight into some of its possible uses.
Since HTTP is the one of the most common transports currently used for SOAP messaging the inherit limitations of using it behind firewalls will hinder its use for asynchronous message processing. For example, an HTTP connection may timeout before a response message can be returned. If the request message's wsa:ReplyTo EPR used the anonymous URI then the response message would have no way of being returned to the source. By using WS-Polling the source can reestablish a connection with the destination and wait for (i.e. request) the response message.
When using WS-RM using the anonymous URI in the wsrm:AcksTo EPR can be problematic. By using WS-Polling the "anonymous" side (the client) can establish a new connection allowing the destination/service to send back any response or ACKs. Likewise, using the anonymous URI in the wsa:ReplyTo EPR is problematic, since the RM Destination can not initiate retries to an anonymous EPR. WS-Polling can help this by allowing the use of the "hold-it" URI, or of a Mailbox, and the client polling for responses.
In situations where an endpoint needs to deliver unsolicited messages to an endpoint behind a firewall, such as a notification consumer behind a firewall subscribing to a notification broker, the consumer can use WS-Polling to periodically request notifications. This is akin to turning the HTTP flow around - the HTTP response flows would carry the SOAP request messages and the HTTP request flows would carry the responses. Note: many notification systems already have support for notification consumers to poll for messages - in those cases it is expected that WS-Polling might not be used - or those solutions could migrate to WS-Polling once WS-Polling becomes part of the core SOAP stack.
A service that can not be available all day, every day, can use a Mailbox as the EPR for its clients. When the system does come up it can then retrieve its incoming messages and process them. From the client's point of view the service is up all of the time.
Some Web Service endpoints, due to resource constraints, may need to have control over the rate at which messages are delivered - by using WS-Polling it can choose when and how often to have incoming messages delivered.
It is strongly RECOMMENDED that the communication between Web services be secured using the mechanisms described in WS-Security [WS-Security, Addendum]. In order to properly secure messages, the body and all relevant headers need to be included in the signature. Specifically, any standard messaging headers, such as those from WS-Addressing [WS-Addressing], need to be signed with the body in order to "bind" the two together.
Different security mechanisms may be desired depending on the frequency of messages. For example, for infrequent messages, public key technologies may be adequate for integrity and confidentiality. However, for high-frequency events, it may be more performant to establish a security context for the events using the mechanisms described in WS-Trust [WS-Trust] and WS-SecureConversation [WS-SecureConversation]. It should be noted that if a shared secret is used it is RECOMMENDED that derived keys be used to strengthen the secret as described in WS-SecureConversation.
Requests for messages which are not available to anonymous parties are strongly RECOMMENDED to require usage of WS-Security so that the requestor can be authenticated and authorized to access the indicated messages. Similarly, integrity and confidentiality SHOULD be used whenever messages have restricted access.
Recipients of messages are RECOMMENDED to validate the signature to authenticate and verify the integrity of the data. Specifically, recipients SHOULD verify that the sender has the right to "speak" for the message.
The following list summarizes common classes of attacks that apply to this protocol and identifies the mechanism to prevent/mitigate the attacks:
The two common uses of WS-Polling require slightly different security solutions. In the case of the client polling the service endpoint, the service endpoint should scope its searching of messages to those that were processed under the same security context as the requesting GetMessage message. In the case of a client polling a Mailbox, it is expected that each soap client that registers with a Mailbox will be issued a unique URL/EPR to be used as its destination address. When the client issues a GetMessage request any number of authentication schemes can be used to verify the identity of the client - once authenticated the Mailbox should then scope its searching of messages to just those that were targeted to that particular client's address.
<?xml version='1.0' encoding='UTF-8'?> <xs:schema targetNamespace='http://www.w3.org/2005/08/ws-polling' xmlns:wsp='http://www.w3.org/2005/08/ws-polling' xmlns:wsa='http://schemas.xmlsoap.org/ws/2004/08/addressing' xmlns:xs='http://www.w3.org/2001/XMLSchema' elementFormDefault='qualified' blockDefault='#all' > <xs:import namespace="http://schemas.xmlsoap.org/ws/2004/08/addressing" schemaLocation="http://schemas.xmlsoap.org/ws/2004/08/addressing"/> <xs:element name='GetMessage'> <xs:complexType> <xs:sequence> <xs:element ref='wsa:MessageID' minOccurs='0' /> <xs:element name='To' minOccurs='0' type="wsa:EndpointReferenceType"/> <xs:element name='extensions' minOccurs='0' /> </xs:sequence> <xs:anyAttribute namespace='##any' processContents='lax'/> </xs:complexType> </xs:element> <xs:element name='NoMessageAvailable' > <xs:complexType> <xs:attribute name='reason' type='xs:QName' /> <xs:anyAttribute namespace='##any' processContents='lax' /> </xs:complexType> </xs:element> <xs:complexType name="StatusRequested"> <xs:sequence> <xs:element ref='wsa:MessageID' minOccurs='0' /> <xs:element name='To' minOccurs='0' type="wsa:EndpointReferenceType"/> <xs:element name='extensions' minOccurs='0' /> </xs:sequence> <xs:anyAttribute namespace='##any' processContents='lax'/> </xs:complexType> <xs:complexType name="Status"> <xs:sequence> <xs:element ref='wsa:MessageID' minOccurs='0' /> <xs:element name='To' minOccurs='0' type="wsa:EndpointReferenceType"/> <xs:element name='extensions' minOccurs='0' /> </xs:sequence> <xs:attribute name='messagesPending' type='xs:boolean' use='required' /> <xs:anyAttribute namespace='##any' processContents='lax'/> </xs:complexType> </xs:schema>
<wsdl:definitions targetNamespace='http://www.w3.org/2005/08/ws-polling' xmlns:wsp='http://www.w3.org/2005/08/ws-polling' xmlns:wsdl='http://schemas.xmlsoap.org/wsdl/' xmlns:xs='http://www.w3.org/2001/XMLSchema' > <wsdl:types> <xs:schema> <xs:import namespace='http://www.w3.org/2005/08/ws-polling' schemaLocation='http://www.w3.org/2005/08/ws-polling.xsd' /> </xs:schema> </wsdl:types> <wsdl:message name='GetMessage'> <wsdl:part name='body' element='wsp:GetMessage'/> </wsdl:message> <wsdl:message name='NoMessageAvailable' <wsdl:part name='body' element='wsp:NoMessageAvailable'/> </wsdl:message> <wsdl:message name='GetMessageResponse'> <wsdl:part name='body' element='xs:any'/> </wsdl:message> <wsdl:portType name='Polling' > <wsdl:operation name='GetMessage' > <wsdl:input message='wsp:GetMessage' /> <wsdl:output message='wsp:GetMessageResponse' /> </wsdl:operation> </wsdl:portType> </wsdl:definitions>