Subject: Re: [alto] Error codes in ALTO

From: Richard Alimi <[email-masked]>
Date: Tue, 7 May 2013 00:09:04 -0700

Thanks Michael!  A couple of things inline:

On Fri, Mar 22, 2013 at 12:19 PM, Scharf, Michael (Michael) <
[email-masked]> wrote:

> Coming back to this, after some research...
>
> > -----Original Message-----
> >       I also would like not to replicate and, for the sake of
> > discussion, say, return (-1) or bytes read to the ALTO layer.
> >
> >       But the current status is more complicated. We already
> > have a mixed bag of things crossing layers.
> >
> >       We already replicate ALTO error codes into HTTP
> > (ALTO->HTTP direction)
> >
> >       "   The HTTP status codes corresponding to each ALTO
> > Error Code are
> >          defined to provide correct behavior with HTTP
> > intermediaries and
> >          clients.  When an ALTO Server returns a particular
> > ALTO Error Code,
> >          it MUST indicate one of the corresponding HTTP
> > status codes in
> >       Table 1 in the HTTP response. "
> >
> > Right.  So one other way would be to not specify this, and
> > leave it up to servers to pick an HTTP status that seems
> > reasonable.  The general idea here was "make sure we still
> > get reasonable behavior when we talk through intermediaries",
> > but if there are better ways to handle this than that would be great.
>
> A reasonable design of an ALTO (client) implementation separates HTTP
> processing from the ALTO protocol engine. The former is mostly a generic
> HTTP instance (e.g., interfacing the well-known curl library), while the
> latter realized the ALTO message parsing etc. In normal operation, both
> "layers" are mostly independent.
>
> However, the RESTful design requires that ALTO error messages have to be
> handled both in the HTTP layer as well as in the ALTO layer. Specifically,
> the HTTP layer will have to decide based on the HTTP error code whether to
> pass a response to the ALTO layer for further ALTO error message
> processing, whether to do something else, or whether to consider the query
> as an entire failure. That distinction is much simpler if the implementor
> knows the HTTP error codes that require further processing not only by the
> HTTP logic, but also by the ALTO logic.
>
> Thus, for interoperability it seems indeed useful that the ALTO protocol
> spec exactly defines the HTTP error codes for any ALTO error type (i.e.,
> error code 400 in spec -14). I don't see a good reason to change that - it
> would make the HTTP logic in an ALTO implementation more complex and less
> interoperable, because the implementor of a client has to guess what a
> server might return.
>
> => Spec -14 seems fine regarding that detail.
>

We had an offline discussion with Ben, Martin (T), and Martin (S) about
exactly this problem.  The guidance was that we shouldn't specify the exact
HTTP status code in the ALTO spec.  The concern was that if a server
returned a different status code for some reason (but it still indicated an
error from the 400 range), the ALTO client may be needlessly surprised.

For the next revision (coming out very shortly), we've removed the explicit
guidance on which HTTP status code to set, and replaced it with generic
guidance indicating that the status code must provide appropriate behavior
at HTTP intermediaries.

I know this is a contentious point, so I'd expect discussion during last
call.

>
> >       And we ask clients to interpret HTTP status codes
> > (HTTP->ALTO direction)
> >
> >       "  o  Return an HTTP 503 ("Service Unavailable") status
> > code to the ALTO
> >             Client.  As indicated by [RFC2616
> > <http://tools.ietf.org/html/rfc2616> ], a the Retry-After HTTP header
> >             may be used to indicate when the ALTO Client
> > should retry the
> >             request."
> >
> > Yes.  I tend to disagree with having this statement in here
> > for exactly the reasons you point out, but it was added after
> > AD feedback saying it was needed to meet the ALTO requirements.
>
> In addition to error HTTP 400, the ALTO spec right now further requires
> special actions on HTTP 503 ("Service Unavailable") and HTTP 307
> ("Temporary Redirect") status codes.
>
> For HTTP 307, the ALTO spec must exactly define whether the redirection
> URI provides the same resource type, or whether it is possibly different
> (e. g., it could be the resource directory of another server with other
> maps). From an implementation perspective, both variants are very
> different. In the former case, the HTTP library can internally realize the
> redirect (e. g., using CURLOPT_FOLLOWLOCATION in the curl library); this is
> probably the simpler variant because it is totally transparent.
> Alternatively, the redirection has to be handled by the ALTO logic, which
> is more heavyweight. Both variants are possible, but an implementor must
> know whether to activate automatic redirect support in HTTP libraries such
> as curl, or not.
>
> => The ALTO spec must specify exactly what type of URI HTTP 307 returns.
>

Thanks for doing this research.   Let's assume for a moment that
CURLOPT_FOLLOWLOCATION was set, and the target of the redirection was a
resource directory.  Would that be a problem?  Presumably the client would
get back a HTTP 300 (Mulitple Choices), and then go from there.  If it
included the direct URI for the corresponding resource at the target
server, then it would be done in a single step.

Thoughts?

>
> For HTTP 503, my current understanding is that an automatic "retry-after"
> is not supported by several HTTP libraries or clients, i. e., an ALTO
> implementation will possibly have to implement the retry timer etc. on its
> own. Still, it seems reasonable to me to rely on a standard HTTP error code
> for that. The motivation is as follows: If more HTTP libraries support this
> error code internally in future, this would at least simplify the design of
> future ALTO implementations.
>
> => Using HTTP error code 503 as in spec -14 seems reasonable to me.
>
> Michael

---

From: Ben Niven-Jenkins <[email-masked]>
Date: Tue, 7 May 2013 08:41:03 +0100

Michael,

> A reasonable design of an ALTO (client) implementation separates HTTP processing from the ALTO protocol engine. The former is mostly a generic HTTP instance (e.g., interfacing the well-known curl library), while the latter realized the ALTO message parsing etc. In normal operation, both "layers" are mostly independent.
> 
> However, the RESTful design requires that ALTO error messages have to be handled both in the HTTP layer as well as in the ALTO layer. Specifically, the HTTP layer will have to decide based on the HTTP error code whether to pass a response to the ALTO layer for further ALTO error message processing, whether to do something else, or whether to consider the query as an entire failure.

It could also use the presence of an app/alto-error (or whatever the media type is) message body & punt that to the ALTO layer.

Without an ALTO specific error response in the message body HTTP doesn't give much room for providing rich error responses anyway, so the ALTO layer would be rather constrained with what it can do with just a HTTP status of 4xx or 5xx as there is unlikely to be a 1:1 mapping between ALTO errors and HTTP status codes.

Ben

> That distinction is much simpler if the implementor knows the HTTP error codes that require further processing not only by the HTTP logic, but also by the ALTO logic.
> 
> Thus, for interoperability it seems indeed useful that the ALTO protocol spec exactly defines the HTTP error codes for any ALTO error type (i.e., error code 400 in spec -14). I don't see a good reason to change that - it would make the HTTP logic in an ALTO implementation more complex and less interoperable, because the implementor of a client has to guess what a server might return.