Default HTTP Binding

Status

This is an attempt of a write-up of a default HTTP binding based on
discussions within the XML Protocol WG TBTF. The document has no status
whatsoever nor does it necessarily represent consensus within the TBTF or
within the XML Protocol WG as a whole.

0 Introduction

This SOAP binding specification adheres to the SOAP Binding Framework ([ref
to binding framework]), and as such uses abstract properties as a descriptive
tool for defining the functionality of certain features.

Properties are named with XML qualified names (QNames).

Property values are determined by the Schema type of the property, as
defined in the specification which introduces the property.

Standard Prefix Mappings

The following are standard prefix mappings which we assume to hold throughout
this document.

Here I think we should say that the request part is mapped to
a HTTP request and the response to a HTTP response - obvious but worth saying.

3 Message Exchange Operation

The Transport Binding Framework [ref], Transport Message Exchange Pattern
Specifications eg [ref] and Feature Specifications eg [ref] each describe the
properties they expect to be present in a transport message exchange context
when control of that context is passes between the local SOAP Node and a binding
instance and vice versa.

The Transport Binding Framework [ref] , Transport Message Exchange Specifications
eg. [ref] and Feature Specifications, describe the preconditions applied during
the transfer of control of a transport message exchange context between a SOAP
Node and a local binding instance. Application of these preconditions resolve
the transport message exchange pattern in operation, the role of the local SOAP
Node with respect to the exchange pattern and that the transport message exchange
context contains the property values necessary to the operation of any active
features.

[gd] I think that this paragraph could profitably be
rewritten in more straightforward language, and perhaps belongs more aptly
in the framework doc itself, rather than the binding.

3.1 Single Request-Response Exchanges

The http://www.w3.org/2001/09/soap/transport-mep/single-request-response/
transport message pattern is described in [ref to mep description].

For binding
instances conforming to this specification:

A SOAP Node instantiated at an HTTP client may take on the role (i.e. the
property single:Role) of RequestingSOAPNode.

A SOAP Node instantiated at an HTTP server may take on the role (ie.
the property single:Role) of RespondingSOAPNode.

In the state tables below, the states are defined as values for the property
"single:State" [ref to MEP], and are
of type "single:StateType" (an enumeration over xsd:string).

Failure reasons as specified in the tables represent values of the property
"transport:FailureReason" - their values
are QNames. If an implementation enters the "Fail" state, the transport:FailureReason
property will contain the value specified for the particular transition.

[gd] The single:Role property is an enumeration over xsd:string,
with at least the two values above, defined in the MEP spec. As indicated, the
states and states property are also defined in the MEP spec.

3.1.1 Behaviour of Requesting SOAP Node

The overall flow of the behaviour of a Requesting SOAP Node follows the
outline state machine description contained in [ref single-request-response tmep
decription].

[skw] std included here, some suggest we should include
it here, others suggest referencing the mep description and avoiding the
repetition

[skw] Preconditions for entering this first state should be
part of the single request response mep description

3.1.1.1 Requesting State

Statename

Requesting

Preconditons

See [ref section of mep description]

Description

Formulate and send HTTP
Request (see table below)

Actions on Leaving State

Transitions

Event/Condition

NextState

Failure Reason

Successfully sent HTTP Request

Waiting

N/A

Failure to send HTTP Request

Fail

fail:TransmissionFailure

HTTP Request Fields

HTTP Method

POST (the use of other HTTP methods is currently undefined
in this binding).

Request URI

The value of the URI carried in the transport:ImmediateDestination
property of the transport message exchange context.

Content-Type header

"text/xml"
according to RFC 2376[ref]

Additional Headers

Generated in accordance with the rules for the
binding specific expression of any optional features in use for this message
exchange eg. SOAPAction (see section 4).

HTTP entity body

XML 1.0 serialisation of
the SOAP message XML Infoset carried in the transport:CurrentMessage
property of the transport message exchange context.

[skw] Note that we have said nothing about attachments here.
The simple interpretation is that this binding does not support attachments. I
think that we could do further work to abstract message encapsulation as a
feature... in which case we would have some properties that would influence the
selection of content type in the second step above and which would influence the
message serialisation.

3.1.1.2 Waiting State

Statename

Waiting

Preconditons

None

Description

Wait for HTTP Response

Actions on Leaving State

Instantiate or replace the property transport:ImmediateSender
with a URI value that denotes the sender of the HTTP response (if known)

In all cases, any HTTP headers that are significant to features expressed outside the SOAP
envelope are processed in accordance with the relevant feature specification.

Transitions

Event/Condition

NextState

Failure Reason

Received HTTP Response Status Line and HTTP
Headers

(see status code table below)

(see status code table below)

Reception Failure

Fail

fail:ReceptionFailure

The following table details the HTTP status code dependent transitions upon
reception of an HTTP status line and response headers.

[skw] This is a large table and it would be good shrink
it somewhat. It doesn't cover all generally possible HTTP status codes and may
cover more than it should. This is one that we should be able to address provided
the direction and style are to people's taste.

[gd] Do we need the "*xx" rows at all?

HTTP Status Code

HTTP reason phrase (informative)

Significance/Action

NextState

2xx

Successful

200

OK

The Response Message follows in HTTP response entity body.

Receiving

202

Accepted

The Request Message has been received and processed.
Then entity body of the HTTP response MAY contain a Response Message.

[skw] Don't really know what we should do here.
HTTP gives guidance on what should be in the entity body, but seemingly
in terms of what information you might present to the user of the user-agent.
One could provide semantically similar information within a SOAP Response
Message - in which case this follows the RR pattern. Alternatively, the
HTTP entity body could be 'empty' (in which case 202 should be used) or
may not contain a SOAP message (to be picked up later....]. We could define
that the default HTTP binding never returns this status code (perhaps).

204

No Content

The Request message has been received and processed. The HTTP response
MUST NOT contain an entity body. The transport message exchange is regarded
as having completed successfully.

[skw] This seems to have turned RR into single
direction one-way (client to server). ie. this breaks the request-response
pattern. Could take the view that this status code is an error when engaged
in a single-request-response exhange or a short-hand for an empty Response
Message - ie. a Response-Message that is just an empty envelope as opposed
to no-response.

Success

Instantiated or replaced Property QName

Property Value

transport:CurrentMessage

Replace contents with a value that
represents and empty SOAP Envelope.

transport:ImmediateSender

If known instantiate this property
with a URI denoting the sender of the HTTP response.

3xx

Redirection

The requested resource has moved and the HTTP request SHOULD be retried using the URI carried in the associated Location
header as the request-URI for the POST request.

[skw] RFC2616 states that these response codes
SHOULD NOT be handled automatically except when the request method is
GET or HEAD (which is not the case for this binding). Otherwise it suggests
that the user should be involved in handling the redirection. Certainly
looks like 301, 302, 303, 305 and 307 may be amenable to automatic
processing - in which case I think that the entity body of the HTTP response
should be discarded and the HTTP request message resend with a Request-URI
taken from the Location header of this response.

Requesting

4xx

Client Error

400

Bad Request

Indicates a problem with the received HTTP Request Message. This may include
a malformed XML in the Request-Message envelope. This operation SHOULD
NOT be repeated with the same message content. The transport message exchange
is regarded has having completed unsuccessfully.

Fail

Instantiated or replaced Property QName

Property Value

transport:FailureReason

fail:BadRequest

401

Unauthorized

Indicates that the HTTP Request requires
authorization. If available this engages the Simple Authentication feature
specified in [ref Simple Authentication Feature ]

[skw] At present this is more of a hook, we have
not (yet) described a simple authentication feature or an HTTP specific
expression of that feature.

Requesting

Instantiated
or replaced Property QName

Property Value

transport:FailureReason

fail:AuthenticationFailure

If the simple authentication feature is unavailable or
the operation
of simple authentication ultimately fails, then the transport message
exchange is regarded as having completed unsuccessfully.

Fail

Instantiated
or replaced Property QName

Property Value

transport:FailureReason

fail:AuthenticationFailure

405

Method not allowed

Indicates that the peer HTTP server does not support the requested HTTP method
at the given request URI. The transport message exchange is regarded has
having completed unsuccessfully.

Fail

Instantiated or replaced Property QName

Property Value

transport:FailureReason

fail:BindingMismatch

415

Unsupported Media Type

Indicates that the peer HTTP server does not support Content-type used
to encode the Request Message. The transport message exchange is regarded
has having completed unsuccessfully.

Fail

Instantiated or replaced Property QName

Property Value

transport:FailureReason

fail:BindingMismatch

427

SOAPAction Required

Indicates that the peer HTTP server implements
the OPTIONAL SOAPAction feature and that it requires that this node provide
a SOAPAction header when resubmitting a similar HTTP request. The
transport message exchange is regarded has having completed unsuccessfully.

In requesting SOAP nodes that support the OPTIONAL SOAPAction feature,
the behaviour described in [ref SOAPAction Feature Spec] is applied.

Fail

5xx

Server Error

500

Internal Server Error

Indicates that the Response Message contained in the following HTTP response
entity body may contain an SOAP Fault. Other internal server errors may
be the cause of this status code. The local binding instance continues
to receive the incoming message.

Receiving

Instantiated or replaced Property QName

Property Value

transport:FaultHint

true

3.1.1.3 Receiving

Statename

Receiving

Preconditons

Description

Receive HTTP response entity
body.

Actions on Leaving State

On transitions to Success,
instantiate or replace the property transport:CurrentMessage
with a value that represents the received Response Message.

Transitions

Event/Condition

NextState

Failure Reason

Well formed Response Message Received

Success

Reception Failure (broken connections etc.)

Fail

fail:ReceptionFailure

Packaging Failure (inc. mismatched
Content-Type)

Fail

fail:PackagingFailure

Malformed Response Message, eg malformed XML,
invalid SOAP Envelope

Fail

fail:BadResponseMessage

3.1.1.4 Success and Fail

These are the terminal states of for a given instance of a
single-request-response transport message exchange. Control over the transport
message exchange context returns to the local SOAP node.

3.1.2 Behaviour of Responding SOAP Node

The overall flow of the behaviour of a Requesting SOAP Node follows the
outline state machine description contained in [ref single-request-response tmep
decription].

[skw] std included here, some suggest we should include
it here, others suggest referencing the mep description and avoiding the
repetition

[skw] Preconditions for entering this first state should be
part of the single request response mep description. The receiving binding
brings a transport message exchange context into existence for the inbound
message instantiates it in a generic receiving state.

3.1.2.1 Receiving

Statename

Receiving

Preconditons

Reception of an HTTP POST request
at an HTTP endpoint bound to the local SOAP Node.

Description

Receive and validate the inbound
Request Message

Actions on Leaving State

Transitions

Event/Condition

NextState

Action

Receive HTTP POST Request containing well
formed Request Message.

Processing

Instantiate or replace the property transport:ImmediateSender
with a URI value that denotes the sender of the HTTP request (if known)

Instantiate or replace the property transport:CurrentMessage
with a value that represents the received Request Message.

Any HTTP headers that are significant to features expressed outside the SOAP
envelope (eg SOAPAction) are processed in accordance with the relevant feature
specification.

This change of state represents a transfer of control of the inbound
transport message exchange context to the local SOAP node.

Receive HTTP POST Request that does malformed
Request Message

Fail

The message is deemed to have been intended
for the local SOAP node, but is deemed badly formed: ill-formed XML, does
contain a valid SOAP envelope. The local SOAP node generates SOAP Fault
message in accordance with the table below which it send in the
corresponding HTTP response message, accompanied by a status code value
appropriate to the particular fault.

The transport message exchange context may be destroyed or considered
not to have been created.

[skw] As described this model tends to hide a malformed
message from the local SOAP Node and handle the malformation in the binding -
basically because it would not be possible to instantiate the CurrentMessage to
pass up for processing. An alternate formulation might be to allow
CurrentMessage to carry badly formed messages and let the SOAP processor/node
deal with it. As presented here we can have define the bindings behaviour with
respect to particular failures.

In the text to follow, the prefix "action" is mapped to the URI "http://www.w3.org/2001/09/soap/binding/defaultHTTP/SOAPAction/"

Feature Description

Some SOAP Receivers using this binding might need certain information to be
readily available outside the message envelope. This binding uses an
externalised expression of the SOAP Action feature to supply this information.

Use of the SOAP Action feature is OPTIONAL. SOAP Receivers MAY use it as a
hint to optimise processing, but SHOULD NOT require its presence in order to
operate. Support for SOAPAction is OPTIONAL in implementations. Implementations
SHOULD NOT generate or require SOAPAction UNLESS they have a particular purpose
for doing so (e.g., a SOAP Receivers specifies its use).

If a SOAP Receiver does require the action:SOAPActionURI
property in order to operate, it MAY respond to requests which either convey
an unrecognised action:SOAPActionURI value
or convey no action:SOAPActionURI value with
a response containing an action:RequiredSOAPActionURI
property. The SOAP Receiver SHOULD ensure that an HTTP status code of 427
(SOAPAction required) is returned to the corresponding HTTP client.

The action:SOAPActionURI and action:RequiredSOAPActionURI
properties are represented in HTTP using the HTTP headers SOAPAction and Required-SOAPAction
respectively. The following table shows the points at which the property values
and HTTP header values are exchanged.

HTTP Client

Property Name

Request

Response

action:SOAPActionURI

If action:SOAPActionURI
property is present in the transport message exchange context, it's
value is sent as the value of a SOAPAction HTTP header

N/A

action:RequiredSOAPActionURI

N/A

If a Required-SOAPAction HTTP header is present, it's
value is inserted into the transport message exchange context as the value
of the action:RequiredSOAPActionURI property.

HTTP Server

Property Name

Request

Response

action:SOAPActionURI

If a SOAPAction HTTP header is present, it's
value is inserted into the transport message exchange context as the value
of the action:SOAPActionURI property.

N/A

action:RequiredSOAPActionURI

N/A

If an action:RequiredSOAPActionURI
property is present in the transport message exchange context, it's value
is sent as the value of a Required-SOAPAction HTTP header

HTTP Header Syntax

The syntax for the SOAPAction and Required-SOAPAction HTTP headers fields is
defined as follows: