Hi Sebastian, all,
We went ahead with an attempt to revise the error codes. Here is a
potential new text:
Any comments are appreciated.
Richard
----------------------------
8.5.1. Media Type
The media type for an ALTO Error Response is "application/
alto-error+json".
8.5.2. Response Format and Error Codes
An ALTO Error Response MUST include the "code" key in the "meta"
field of the response. The value of "code" MUST be an ALTO Error
Code defined in Table 1. Note that the ALTO Error Codes defined in
Table 1 are limited to support the error conditions needed for
purposes of this document. Additional status codes may be defined in
companion or extension documents.
+-----------------------+-------------------------------------------+
| ALTO Error Code | Description |
+-----------------------+-------------------------------------------+
| E_SYNTAX | Parsing error in request (including |
| | identifiers) |
| E_JSON_VALUE_TYPE | JSON Value of unexpected type |
| E_MISSING_FIELD | Required JSON field missing |
| E_INVALID_FIELD_VALUE | The value of a JSON field is invalid |
+-----------------------+-------------------------------------------+
Table 1: Defined ALTO Error Codes.
Specifically, after an ALTO Server receives a query, it needs to
check the syntax of the query, and indicates a syntax error using the
error code E_SYNTAX. A specific type of syntax error is
E_JSON_VALUE_TYPE, which indicates that a JSON type is incorrect
(e.g., a request uses a JSONString when a JSONNumber is expected).
An ALTO Server may return either the general E_SYNTAX error code or
the more specific E_JSON_VALUE_TYPE error code, if possible.
A query without syntax error may still be invalid. An error case is
that the query misses a required field. The server indicates such an
error using error code E_MISSING_FIELD. This document defines
required fields for Network Map Filtering (Section 11.3.1.3), Cost
Map Filtering (Section 11.3.2.3), Endpoint Properties
(Section 11.4.1.3), and Endpoint Cost (Section 11.5.1.3). For an
E_MISSING_FIELD error, the server may include the optional "field"
key in the "meta" field of the response, to indicate the missing
field.
A query with correct query fields may specify a wrong value for a
field. For example, a cost map filtering query may specify a wrong
value of CostMode in the "cost-type" field (Section 11.3.2.3). The
server indicates such an error with error code E_INVALID_FIELD_VALUE.
For an E_INVALID_FIELD_VALUE error, the server may include the
optional "field" key in the "meta" field of the response, to indicate
the field that contains the wrong value. The server may also include
the optional "value" key in the "meta" field of the response to
indicate the wrong value that triggered the error.
If multiple errors are present in a single request (e.g., a request
uses a JSONString when a JSONNumber is expected and a required field
is missing), then the ALTO Server MUST return exactly one of the
detected errors. However, the reported error is implementation
defined, since specifying a particular order for message processing
encroaches needlessly on implementation techniques.
On Wed, Oct 2, 2013 at 9:28 AM, Y. Richard Yang <[email protected]> wrote:
> Hi Sebatian,
>
>
> On Tue, Oct 1, 2013 at 4:49 PM, Sebastian Kiesel <[email protected]>wrote:
>
>> Hi Richard,
>>
>> On Tue, Oct 01, 2013 at 03:24:15PM -0400, Y. Richard Yang wrote:
>> > On Tue, Oct 1, 2013 at 2:33 AM, Sebastian Kiesel <[email protected]
>> >wrote:
>> > > > Req. AR-9: An ALTO client protocol specification MUST define
>> > > > mechanisms that can be used by the ALTO server to indicate that a
>> > > > host-group descriptor used by the ALTO client is of an
>> unsupported
>> > > > type, or that the indicated mapping mechanism could not be used.
>> > >
>> > > Req. AR-9: Full compliant: 8.5.2
>> > >
>> > > Comment:
>> > >
>> > > The error code E_JSON_VALUE_TYPE can be used, though it might be
>> > > useful to define an own, less generic error message.
>> > >
>> > >
>> > Do you suggest that we make a small change to add a more specific error
>> > code, say E_INVALID_HOST_GROUP_DESCRIPTOR? The same as below...
>>
>> I think we should add a E_INVALID_ADDRESS_TYPE to the table
>> in section 8.5.2.
>>
>>
>> (IMO "invalid address type" is more consistent with the terminology
>> used in the protocol document.)
>>
>>
> Agree. Here is a proposal for a quick change on handling errors.
>
> - Errors come from client query, which consists of the following:
>
> network map filtering:
>
> object {
> PIDName pids<0..*>;
> [AddressType address-types<0..*>;]
> } ReqFilteredNetworkMap;
>
>
>
> cost map filtering:
>
> object {
> CostType cost-type;
> [JSONString constraints<0..*>;]
> [PIDFilter pids;]
> } ReqFilteredCostMap;
>
> object {
> PIDName srcs<0..*>;
> PIDName dsts<0..*>;
> } PIDFilter;
>
>
> endpoint properties:
>
> object {
> EndpointPropertyType properties<1..*>;
> TypedEndpointAddr endpoints<1..*>;
> } ReqEndpointProp;
>
>
> endpoint cost:
>
> object {
> CostType cost-type;
> [JSONString constraints<0..*>;]
> EndpointFilter endpoints;
> } ReqEndpointCostMap;
>
> object {
> [TypedEndpointAddr srcs<0..*>;]
> [TypedEndpointAddr dsts<0..*>;]
> } EndpointFilter;
>
>
>
> After the server gets a query, the server first checks the syntax, an
> error happens if the syntax is wrong: E_SYNTAX
>
> Suppose the syntax is correct, and then the server needs to look at each
> field in the client query. We can identify three cases:
> 1). the field is a valid field;
> 2). the field is not defined by the protocol (E_UNKNOWN_FIELD; note that
> 8.3.8 says ignore unknown field);
> 3. a required field is missing (E_FIELD_MISSNG).
>
> Next look at case 1), an error can happen if the value is invalid (e.g.,
> invalid cost-type, or address type, ...). Hence, a generic error code can
> be: E_INVALID_FIELD_VALUE.
>
> As a result, we have 4 (or 3, if we do not include unknown field) generic
> error codes that cover all error cases. For more informative errors, the
> error message body can identify the field involved.
>
> Next, we can refine the errors for invalid values to give more details.
> Here are the fields defined so far:
>
> pids,
> address-types,
>
> cost-type,
> constraints,
> pids.srcs,
> pids.dsts,
>
> properties,
> endpoints,
>
> cost-type,
> constraints,
> endpoints.srcs,
> endpoints.dsts,
>
> We can see that the current error codes have not completely covered all
> fields (i.e., covered only INVALID_COST_MODE, INVALID_COST_METRIC, and
> INVALID_PROPERTY_TYPE). Instead of hardcoding all fields, how about we
> define the following error msg:
>
> {
> "meta": {
> "code": one of the generic error codes;
> ["field": optional identify the field triggered the error;]
> ["value": optional identify the wrong value when error is
> E_INVALID_FIELD_VALUE]
> ["message": gives a text description]
> }
> }
>
> The preceding is a simple change in Sec. 8.5.2, and is more extensible.
> How does this sound?
>
> Thanks again!
>
> Richard
>
>
>> Thanks
>> Sebastian
>>
>
>
_______________________________________________
alto mailing list
[email protected]
https://www.ietf.org/mailman/listinfo/alto
