Bill the Plumber

Just finished draft 4 of REST-* Messaging.  Please check our our discussion group if you want to talk more about it.  Here’s a list of resources and their corresponding relationships for a high level overview.  See the spec for more details.  It relies heavily on Link headers.  The current draft shows a lot of example HTTP request/responses to give you a good idea of what is going on.

Destination

A queue or a topic resource.

Relationships:

• post-message – link to POST/create a message to a queue or topic.  This can be
• post-message-once – link to POST/create a message to a queue or topic using the POST-Once-Exactlly (POE) pattern
• post-batch – POST/create a batch of messages using Atom or Multipart
• post-batch-once – POST/create a batch using the POE pattern.

Message

Every message posted creates a message resource that can be viewed for adminstration, auditing, monitoring, or usage.

Links Relationships:

• reply-to.  Destination that you can reply to
• reply-to-once.  Destination that you can reply to once using the POST-Only-Once pattern
• reply-to-batch. Destination that you can reply with a batch of messages
• reply-to-batch-once.  Batch using POE.
• next.  If pulling from a topic, messages will have this link.  This is the next message after this one.
• acknowledgement.  If pulling from a queue, this link allows you to change the state of the message to acknowleged or not.
• generator. Destination that the message came from

Topic

Has the same links as Destination with these added:

Link Relationships:

• next.  GET the next incoming message.  Clients should use the Accept-Wait header to set a blocking timeout (see later).
• last.  Last posted message to the topic
• first.  First message posted to topic, or, the first message that is still around.
• subscribers. URL that allows you to view (GET) or create/register (POST) a list of URLs to forward messages to.

Queue

Same as Destination, but these additional link relationships:

Link Relationships:

• poller.  Alias to the next available message in the queue.  Returns a message representation along with a Content-Location header pointing to the real one.  a POST is required to access this because the state of the queue is changed.
• subscribers.  Same as topic push model.

I wanted to add acknowledgement to the queue consumer pull model in REST-* Messaging.  The way it would work is that consumers do a POST on the queue’s URL.  They receive the message as well as a Link header pointing to an acknowledgement resource.  When the client consumer successfully processes the message, it posts a form parameter, acknowledge=true to the acknowledgement link.

There is a problem with this though.  The design is connectionless to honor the stateless REST principle.  So there is no specific session resource that the client consumer is interacting with.  The consumer may never acknowledge the message, so I need the server to re-enqueue the message and deliver it to a new consumer.  The problem is, what if the old consumer tries to acknowledge after the message is re-enqueued or even after it is redelivered to a different consumer?

I first thought of letting the first consumer to acknowledge win and do something like POST-Once-Exactly (POE).  The problem with this is, what if there’s a network failure and the consumer doesn’t know if the acknowledgement happened or not?  It would redeliver the message and get back a Method Not Allowed response error code.  With this code, the consumer doesn’t know if somebody else acknowledged the message or if the older request just went through.  So, I went with a conditional POST.  The acknowledgement link, when performing a GET on it, would return an ETag header that the consumer must transmit with the acknowledgement POST.  If the message was re-enqueued, then the underlying ETag would change, and the conditional post would fail for the older consumer.

Still this solution is suboptimal because an additional GET request needs to be executed.  It is also subject to a race condition.  What if the message is re-enqueued before the consumer does a GET on the acknowledgement resource?  SO, what I decided to do was embed the etag value with the acknowledgement link.  For example:

1. Consume a message
Request:

POST /myqueue/consumer

Response:

HTTP/1.1 200 OK
Link: </myqueue/messages/111/acknowledgement>; rel=acknowledgement; etag=1
Content-Type: ...

...  body ...

2. Acknowledge the message
Request:

POST /myqueue/messages/111/acknowledgement
If-Match: 1
Content-Type: application/x-www-form-urlencoded

acknowledge=true

Success Response:

HTTP/1.1 204 No Content

Response when it was updated by somebody else.

HTTP/1.1 412 Precondition Failed

POE Redelivery Response.  It was already successfully updated by the consumer.

HTTP/1.1 405 Method Not Allowed

One thing the HTTP specification does not have is a “Server Timeout” response code.  The 408 and 504 response codes are the only thing that comes close.  The idea of a “Server Timeout” code is that the server received the request, but timed out internally trying to process the request.  Another thing I think that is missing from HTTP is a way for the client to tell the server how long it is willing to wait for a request to be processed.

I’ve run into both of these scenarios with the REST-* Messaging specification when I have pulling client consumers.  For the “Server Timeout” I decided upon 202, Accepted.  It seems to fit as I can tell the client to try again at a specific URL.  As for the client requesting a wait time?  I invented a new request header:  “X-RS-Wait”.  Its value is the time in seconds that the client wants to wait for a request to be processed.  Maybe there is a standard or drafted protocol I missed in my Google search?

After prototyping, I’m back to writing another draft. This is a little bit more formal draft. I created a OSS project at:

http://sf.net/projects/rest-star

A draft of the PDF is at:

http://reststar-messaging.googlegroups.com/web/REST-Star-Messaging-draft-3.pdf

(You’ll have to click through an additional link that is *very* long). This draft only talks about the Message Publishing Protocol. I still have to write up the topic and queue push and pull model.  To discuss the draft please post at the REST-* Messaging Group.  I’m also looking for people to help prototype the specification.  Post to the RESTEasy developers list if you’re interested.