Subject: Re: [alto] alto-protocol-18 vs. RFC 6708

From: "Y. Richard Yang" <[email-masked]>
Date: Tue, 1 Oct 2013 15:24:15 -0400

Hi Sebastian,

Thanks a lot for the always wonderful work! Please see below.

On Tue, Oct 1, 2013 at 2:33 AM, Sebastian Kiesel <[email-masked]>wrote:

> Dear all,
>
> I tried to match the latest ALTO protocol draft (18) against our
> requirements document (RFC 6708).
>
>
> Management summary
>
> all requirements met.
>
> Future work (extension documents) may be useful in the area of caching,
> see AR-25 below.  Minor beautification possible, see AR-9 below.
>
> Thanks,
> Sebastian
>
> ----- ----- ------
>
> A line
>
> Req. AR-X:   Full compliant : Y.Z
>
> to be read as:
>
> The requirement X from RFC 6708 is fulfilled because of the mechanisms
> or rules specified in section Y.Z of draft-ietf-alto-protocol-18.txt
>
> > 3.  ALTO Requirements
> >
> > 3.1.  ALTO Client Protocol
> >
> > 3.1.1.  General Requirements
> >
> >    Req. AR-1: The ALTO service is provided by one or more ALTO servers.
> >    It may be queried by ALTO clients seeking guidance for selecting
> >    appropriate resource providers.  ALTO clients and ALTO servers MUST
> >    implement an ALTO client protocol.  An ALTO client protocol MUST be
> >    able to transmit ALTO queries from an ALTO client to an ALTO server,
> >    and it MUST be able to transmit the corresponding ALTO replies from
> >    the ALTO server to the ALTO client.
>
> Req. AR-1:  Full compliant: 8.3
>
> >    The detailed specification of an ALTO client protocol is out of the
> >    scope of this document.  In fact, this document does not even assume
> >    that there will be only one single protocol specification.  However,
> >    this document enumerates requirements for ALTO, to be considered when
> >    specifying, assessing, or comparing protocols and implementations.
> >
> >    Req. AR-2: An ALTO client protocol MUST provide adequate mechanisms
> >    for operations and management support, as outlined in RFC 5706
> >    [RFC5706].
>
> Req. AR-2:  Full compliant: 16
>
> > 3.1.2.  Host-Group Descriptor Support
> >
> >    The ALTO guidance is based on the evaluation of several resource
> >    providers or groups of resource providers, considering one or more
> >    rating criteria.  The resource providers or groups of resource
> >    providers are characterized by means of host-group descriptors.
> >
> >    Req. AR-3: An ALTO client protocol MUST support the usage of multiple
> >    host-group descriptor types.
>
> Req. AR-3:  Full compliant: 10.4.1
>
> >
> >    Req. AR-4: ALTO clients and ALTO servers MUST clearly identify the
> >    type of each host-group descriptor sent in ALTO queries or responses.
> >    An ALTO protocol specification MUST provide appropriate protocol
> >    elements.
>
> Req. AR-4:  Full compliant: 10.4.2.3.
> >
> >    Req. AR-5: An ALTO client protocol MUST support the host group
> >    descriptor types "IPv4 address prefix" and "IPv6 address prefix".
> >    They can be used to specify the IP address of one host, or an IP
> >    address range (in Classless Inter-Domain Routing (CIDR) notation)
> >    containing all hosts in question.
>
> Req. AR-5:  Full compliant: 10.4.3.1, 10.4.3.2
>
> >    Req. AR-6: An ALTO client protocol MUST be extensible to enable
> >    future support of other host-group descriptor types.  An ALTO client
> >    protocol specification MUST define an appropriate procedure for
> >    adding new host-group descriptor types, e.g., by establishing an IANA
> >    registry.
>
> Req. AR-6:  Full compliant: 14.4
>
> >    Req. AR-7: For host-group descriptor types other than "IPv4 address
> >    prefix" and "IPv6 address prefix", the host-group descriptor type
> >    identification MUST be supplemented by a reference to a facility that
> >    can be used to translate host-group descriptors of this type to IPv4/
> >    IPv6 address prefixes, e.g., by means of a mapping table or an
> >    algorithm.
>
> Req. AR-7:  Full compliant: 5, 11.2.1, 14.4
>
> Comment:
>
>     In addition to IPv4/6 addresses/prefixes, the document only
>     defines one host-group descriptor type, namely PIDs. The mapping
>     mechanism from IP prefixes to PIDs ("Network Map") is described
>     in 5 and 11.2.1.
>
>     The IANA registry defined in 14.4 contains a column
>     "Mapping to/from IPv4/IPv6 Addresses".
>
> >    Req. AR-8: Protocol functions for mapping other host-group descriptor
> >    types to IPv4/IPv6 address prefixes SHOULD be designed and specified
> >    as part of an ALTO client protocol, and the corresponding address
> >    mapping information SHOULD be made available by the same entity that
> >    wants to use these host-group descriptors within an ALTO client
> >    protocol.  However, an ALTO server or an ALTO client MAY also send a
> >    reference to an external mapping facility, e.g., a translation table
> >    to be obtained via an alternative mechanism.
>
> Req. AR-8:  Full compliant: 5, 11.2.1
>
> Comment:
>
>     The network map is part of the protocol.
>
>     Due to the extensible nature of JSON/HTTP we will most likely be
>     able to define many kinds of extensions that are compliant to this
>     requirement.
>

> >       Rationale for the previous two requirements: The preferred type of
> >       host-group descriptors are IPv4 and IPv6 prefixes.  However, in
> >       some situations, one party may prefer to use another type, e.g.,
> >       AS numbers.  Usually, applications seeking ALTO guidance work with
> >       IP addresses, e.g., when establishing connections.  Understanding
> >       guiding information that is based on other host-group descriptor
> >       types, i.e., mapping from these other types to IP prefixes and
> >       back, may be a non-trivial task.  Therefore, before a party may
> >       use other host-group descriptor types, they must provide a mapping
> >       mechanism to IP prefixes.
>
>
Good point. I think that we will need some extensions to handle the case
such as AS numbers.

>    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...

Thanks!

Richard

> >    Req. AR-10: An ALTO client protocol specification MUST define
> >    mechanisms that can be used by the ALTO client to indicate that a
> >    host-group descriptor used by the ALTO server is of an unsupported
> >    type, or that the indicated mapping mechanism could not be used.
>
> Req. AR-10: 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.
>

>
> > 3.1.3.  Rating Criteria Support
> >
> >    Req. AR-11: An ALTO client protocol specification MUST define a
> >    rating criterion that can be used to express and evaluate the
> >    "relative operator's preference".  This is a relative measure, i.e.,
> >    it is not associated with any unit of measurement.  A preferred
> >    rating, according to this criterion, indicates that the application
> >    should prefer the respective candidate resource provider over others
> >    with less preferred ratings (unless information from non-ALTO sources
> >    suggests a different choice, such as transmission attempts suggesting
> >    that the path is currently congested).  The operator of the ALTO
> >    server does not have to disclose how and based on which data the
> >    ratings are actually computed.  Examples could be: cost for peering
> >    or transit traffic, traffic engineering inside the network, and other
> >    policies.
>
> Req. AR-11: Full compliant: 6.1.1.1
> >
> >    Req. AR-12: An ALTO client protocol MUST be extensible to enable
> >    future support of other rating criteria types.  An ALTO client
> >    protocol specification MUST define an appropriate procedure for
> >    adding new rating criteria types, e.g., by establishing an IANA
> >    registry.
>
> Req. AR-12:  Full compliant: 14.2
>
> >    Req. AR-13: ALTO client protocol specifications MUST NOT define
> >    rating criteria closely related to the instantaneous network
> >    congestion state, i.e., rating criteria that have the primary aim to
> >    serve as an alternative to established congestion control strategies,
> >    such as using TCP-based transport.
>
> Req. AR-13:  Full compliant: no such attribute is defined in the document
>
> >    Req. AR-14: Applications using ALTO guidance MUST NOT rely solely on
> >    the ALTO guidance to avoid causing network congestion.  Instead, they
> >    MUST use other appropriate means, such as TCP-based transport, to
> >    avoid causing excessive congestion.
>
> Req. AR-14: Not applicable
>
> Comment:
>
>     This requirement is not about the ALTO Client Protocol
>     (specification|implementation) itself, but about the application
>     using it.
>
> >       Rationale for the previous requirement: One design assumption for
> >       ALTO is that it is acceptable for the host-characteristics
> >       attributes, which are stored and processed in the ALTO servers for
> >       giving guidance, to be updated rather infrequently.  Typical
> >       update intervals may be several orders of magnitude longer than
> >       the typical network-layer packet round-trip time (RTT).
> >       Therefore, ALTO cannot be a replacement for TCP-like congestion
> >       control mechanisms.
> >
> >    Req. AR-15: In the target-independent query mode, the ALTO query
> >    message SHOULD allow the ALTO client to express which host-
> >    characteristics attributes should be returned.
>
> Req. AR-15: Full compliant: 9.2
>
> Comment:
>
>     The ALTO client may use the HTTP GET method with a cost map URI
>     learned from the server's IRD (sec. 9.2)
>
> >    Req. AR-16: In the target-aware query mode, the ALTO query message
> >    SHOULD allow the ALTO client to express which rating criteria should
> >    be considered by the server, as well as their relative relevance for
> >    the specific application that will eventually make use of the
> >    guidance.  The corresponding ALTO response message SHOULD allow the
> >    ALTO server to express which rating criteria have been considered
> >    when generating the response.
>
> Req. AR-16: Full compliant: 11.4.1.3, 11.4.1.6, 11.5.1.3, 11.5.1.6
>
> >    Req. AR-17: An ALTO client protocol specification MUST define
> >    mechanisms that can be used by the ALTO client and the ALTO server to
> >    indicate that a rating criteria used by the other party is of an
> >    unsupported type.
>
> Req. AR-17: Full compliant:  8.5.2
>
> > 3.1.4.  Placement of Entities and Timing of Transactions
> >
> >    With respect to the placement of ALTO clients, several modes of
> >    operation exist:
> >
> >    o  One mode of ALTO operation is that an ALTO client may be embedded
> >       directly in the resource consumer, i.e., the application protocol
> >       entity that will eventually initiate data transmission to/from the
> >       selected resource provider(s) in order to access the desired
> >       resource.  For example, an ALTO client could be integrated into
> >       the peer of a P2P application that uses a distributed algorithm
> >       such as "query flooding" for resource discovery.
> >
> >    o  Another mode of operation is to integrate the ALTO client into a
> >       third party, such as a resource directory.  This third party may
> >       issue ALTO queries to solicit preference on potential resource
> >       providers, considering the respective resource consumer.  For
> >       example, an ALTO client could be integrated into the tracker of a
> >       tracker-based P2P application, in order to request ALTO guidance
> >       on behalf of the peers contacting the tracker.
> >
> >    Req. AR-18: An ALTO client protocol MUST support the mode of
> >    operation in which the ALTO client is directly embedded in the
> >    resource consumer.
>
> Req. AR-18: Full compliant: 12.2, 12.3
>
> >    Req. AR-19: An ALTO client protocol MUST support the mode of
> >    operation in which the ALTO client is embedded in a third party.
> >    This third party performs queries on behalf of resource consumers.
>
> Req. AR-19: Full compliant: 12.1
>
> >    Req. AR-20: An ALTO client protocol MUST be designed in a way that
> >    the ALTO service can be provided by an entity that is not the
> >    operator of the underlying IP network.
>
> Req. AR-20: Full compliant: The ALTO protocol is based on HTTP
>     (Sec.  8.3).  HTTP can be used to access servers anywhere in the
>     Internet, which are operated by arbitrary entities.  No additional
>     single-domain or link-layer-coupled mechanisms (e.g. DHCP, IP
>     multicasting/broadcasts, etc.) are mandated by this document.
>
> >    Req. AR-21: An ALTO client protocol MUST be designed in a way that
> >    different instances of the ALTO service operated by different
> >    providers can coexist.
>
> Req. AR-21: Full compliant: The ALTO protocol is based on HTTP
>     (Sec. 8.3). Servers operated by different entities can coexist.
>
> Comment:
>
>     The ALTO server discovery mechanism, which is out of the scope of
>     this document, may need additional mechanisms for selecting the
>     desired ALTO server operator.
>
> >    Req. AR-22: An ALTO client protocol specification MUST specify at
> >    least one query mode, either the target-aware or the target-
> >    independent query mode.
>
> Req. AR-22: Full compliant: The target-independent query mode
>     is implemented by the Network Map and the Cost Map.
>     "An ALTO Server MUST provide at least one Network Map." (11.2.1)
>     and "This resource [Cost Map] MUST be provided for at least the
>     'routingcost' Cost Metric." (11.2.2).
>
> >    Note that this requirements document does not assume that there will
> >    be only one single protocol specification.
> >
> >    Req. AR-23: An ALTO client protocol specification SHOULD specify both
> >    the target-aware and the target-independent query mode.  If an ALTO
> >    client protocol specification specifies more than one query mode, it
> >    MUST define at least one of these modes as REQUIRED to implement by
> >    ALTO clients and ALTO servers.  Furthermore, it MUST specify an
> >    appropriate protocol mechanism for negotiating between the ALTO
> >    client and ALTO server, which query mode to use.
>
> Req. AR-23: Full compliant: The target-independent query mode MUST
>     be supported (see AR-22).
>
>     The target-aware query mode is implemented by the Endpoint Property
>     Service, which MAY be provided by an ALTO server (11.4.1) and the
>     Endpoint Cost Service, which MAY be provided by an ALTO server
>     (11.5.1).
>
>     The ALTO server adds appropriate entries to its Information Resource
>     Directory (9) if the Endpoint Property Service and/or the
>     Endpoint Cost Service are supported.  The client may then decide
>     whether to access them or the Cost Maps.
>
> >    Req. AR-24: An ALTO client protocol SHOULD support version numbering,
> >    TTL (time-to-live) attributes, and/or similar mechanisms in ALTO
> >    transactions, in order to enable time validity checking for caching,
> >    and to enable comparisons of multiple recommendations obtained
> >    through redistribution.
>
> Req. AR-24: Full compliant: 3.2
>
> >    Req. AR-25: An ALTO client protocol SHOULD allow the ALTO server to
> >    add information about appropriate modes of reuse to its ALTO
> >    responses.  Reuse may include redistributing an ALTO response to
> >    other parties, as well as using the same ALTO information in a
> >    resource directory to improve the responses to different resource
> >    consumers within the specified lifetime of the ALTO response.  The
> >    ALTO server SHOULD be able to express that
> >
> >    o  no reuse should occur.
> >
> >    o  reuse is appropriate for a specific "target audience", i.e., a set
> >       of resource consumers explicitly defined by a list of host-group
> >       descriptors.  The ALTO server MAY specify a "target audience" in
> >       the ALTO response that is only a subset of the known actual
> >       "target audience", e.g., if required by operator policies.
> >
> >    o  reuse is appropriate for any resource consumer that would send (or
> >       cause a third party to send on behalf of it) the same ALTO query
> >       (i.e., with the same query parameters, except for the resource
> >       consumer ID, if applicable) to this ALTO server.
> >
> >    o  reuse is appropriate for any resource consumer that would send (or
> >       cause a third party to send on behalf of it) the same ALTO query
> >       (i.e., with the same query parameters, except for the resource
> >       consumer ID, if applicable) to any other ALTO server that was
> >       discovered (using an ALTO discovery mechanism) together with this
> >       ALTO server.
> >
> >    o  reuse is appropriate for any resource consumer that would send (or
> >       cause a third party to send on behalf of it) the same ALTO query
> >       (i.e., with the same query parameters, except for the resource
> >       consumer ID, if applicable) to any ALTO server in the whole
> >       network.
>
> Req.  AR-25:  Compliant for the current state of the base protocol
>
> Comment:
>
>     Only the first and the last bullet are supported by mechanisms
>     of the underlying HTTP protocol and there are no additional
>     mechanisms defined within the ALTO protocol.
>     So formally speaking this requirement is only partially met.
>     However, this requirement been written down without a specific
>     design pattern for the ALTO protocol in mind. With the HTTP+RESTful
>     approach eventually taken, options #2, #3, and #4 are not really
>     applicable. So for the time being this requirement is sufficiently
>     met. However, future documents on caching and redistribution (e.g.,
>     redistribution of ALTO replies within the P2P application protocol)
>     should re-visit this requirement.
>
> >    Req. AR-26: An ALTO client protocol MUST support the transport of
> >    ALTO transactions, even if the ALTO client is located in the private
> >    address realm behind a network address translator (NAT).  There are
> >    different types of NAT, see [RFC4787] and [RFC5382].
>
> Req. AR-26: Full compliant: The ALTO protocol is based on HTTP
>     (Sec.  8.3). Allowing HTTP traffic is one of the most basic
> requirements
>     for all types of NAT. For detection of "public" IP address see 13.3.
>
> > 3.1.5.  Protocol Extensibility
> >
> >    Req. AR-27: An ALTO client protocol MUST include support for adding
> >    protocol extensions in a non-disruptive, backward-compatible way.
>
> Req. AR-27: Full compliant: 14.1
>
> >    Req. AR-28: An ALTO client protocol MUST include protocol versioning
> >    support, in order to clearly distinguish between incompatible
> >    versions of the protocol.
>
> Req. AR-28: Full compliant.  Due to the very flexible mechanisms for
>     seamlessly extending the protocol (see Req. AR-27), a disruptive
>     update is only needed if the structure of the IRD has to be changed.
>     This can be done by defining a new media type
>     (e.g., alto-directory_v2_0+json) and using the content-type header
>     in the underlying HTTP protocol.
>
> > 3.1.6.  Error Handling and Overload Protection
> >
> >    Req. AR-29: An ALTO client protocol MUST use congestion-aware
> >    transport, e.g., by using TCP.
>
> Req.  AR-29:  Full compliant.  Protocol is based on HTTP (8.3), which
>     does not neccessarily run on top of TCP (see 1.4. of RFC 2616), but
>     de-facto always does.
>
> >    Req. AR-30: An ALTO client protocol specification MUST specify
> >    mechanisms for an ALTO server to inform clients about an impending or
> >    occurring overload situation, or how to leverage appropriate
> >    mechanisms provided by underlying protocol layers.  The mechanisms
> >    MUST provide all of the following options to the server:
> >
> >    o  terminate the conversation with the client,
> >
> >    o  redirect the client to another ALTO server, and
> >
> >    o  request that the client throttle its query rate.
> >
> >       In particular, a simple form of throttling is to let an ALTO
> >       server answer a query with an error message advising the client to
> >       retry the query later (e.g., using a protocol function such as
> >       HTTP's Retry-After header ([RFC2616], Section 14.37)).  Another
> >       simple option is to actually answer the query with the desired
> >       information, but adding an indication that the ALTO client should
> >       not send further queries to this ALTO server before an indicated
> >       period of time has elapsed.
>
> Req. AR-30:  Full compliant:  8.5.3.
>
> >    Req. AR-31: An ALTO client protocol specification MUST specify
> >    mechanisms for an ALTO server to inform clients about its inability
> >    to answer queries due to technical problems or system maintenance, or
> >    how to leverage appropriate mechanisms provided by underlying
> >    protocol layers.  The mechanisms MUST provide all of the following
> >    options to the server:
> >
> >    o  terminate the conversation with the client,
> >
> >    o  redirect the client to another ALTO server, and
> >
> >    o  request that the client retry the query later.
>
> Req. AR-31:  Full compliant:  8.5.3.
>
> >    Note: The existence of the above-mentioned protocol mechanisms does
> >    not imply that an ALTO server must use them when facing an overload,
> >    technical problem, or maintenance situation, respectively.  Some
> >    servers may be unable to use them in that situation, or they may
> >    prefer to simply refuse the connection or not to send any answer at
> >    all.
> >
> > 3.2.  ALTO Server Discovery
>
> Reqs. AR-32 to AR-39: not applicable to this document
>
> > 3.3.  Security and Privacy
> >
> >    Req. AR-40: An ALTO client protocol specification MUST specify
> >    mechanisms for the authentication of ALTO servers or specify how to
> >    leverage appropriate mechanisms provided by underlying protocol
> >    layers.
>
> Req. AR-40: Full compliant: 8.3.5.
>
> >    Req. AR-41: An ALTO client protocol specification MUST specify
> >    mechanisms for the authentication of ALTO clients or specify how to
> >    leverage appropriate mechanisms provided by underlying protocol
> >    layers.
>
> Req. AR-41: Full compliant: 8.3.5.
>
> >    Req. AR-42: An ALTO client protocol specification MUST specify
> >    mechanisms for the encryption of messages or specify how to leverage
> >    appropriate mechanisms provided by underlying protocol layers.
>
> Req. AR-42: Full compliant: 8.3.5.
>
> >    Req. AR-43: An ALTO client is not required to implement mechanisms or
> >    to comply with rules that limit its ability to redistribute
> >    information retrieved from the ALTO server to third parties.
>
> Req. AR-43: Not applicable to this document. See also 15.3.3.
>
> >    Req. AR-44: An ALTO client protocol MUST support different levels of
> >    detail in queries and responses in order to protect the privacy of
> >    users, to ensure that the operators of ALTO servers and other users
> >    of the same application cannot derive sensitive information.
>
> Req.  AR-44:  Full compliant.  Host Group Descriptors are always
>     encoded as TypedEndpointAddr, which allows to use IP prefixes.
>     Therefore it is possible to obfuscate the identity of candidate
>     resource consumers, e.g., by specifying a broader address range
>     (i.e., a shorter prefix length) than a group of hosts in question
>     actually uses, or by zeroing-out or randomizing the last few bits of
>     IP addresses.  However, there is the potential side effect of
>     yielding inaccurate results.
>
> >    Req. AR-45: An ALTO client protocol MAY include mechanisms that can
> >    be used by the ALTO client when requesting guidance to specify the
> >    resource (e.g., content identifiers) it wants to access.  An ALTO
> >    server MUST provide adequate guidance, even if the ALTO client
> >    prefers not to specify the desired resource (e.g., keeps the data
> >    field empty).  The mechanism MUST be designed in a way that the
> >    operator of the ALTO server cannot easily deduce the resource
> >    identifier (e.g., file name in P2P file sharing) if the ALTO client
> >    prefers not to specify it.
>
> Req.  AR-45:  Full compliant.  The optional ("MAY") feature is not
>     defined and therefore, the MUST-statements do not apply.
>
> >    Req. AR-46: An ALTO client protocol specification MUST specify
> >    appropriate mechanisms for protecting the ALTO service against
> >    Denial-of-Service (DoS) attacks or specify how to leverage
> >    appropriate mechanisms provided by underlying protocol layers.
>
> Req.  AR-46:  Full compliant. See 15.5. for ALTO-specific protection
>     strategies. Furthermore, the protocol is based on HTTP, and
>     protecting HTTP-based services against different kinds of attacks,
>     including DoS attacks, is a rather well-understood issue.
>
> -- end --
> _______________________________________________
> alto mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/alto
>

---

From: Sebastian Kiesel <[email-masked]>
Date: Tue, 1 Oct 2013 22:49:25 +0200

Hi Richard,

> 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.)

Thanks
Sebastian

---

From: Spencer Dawkins <[email-masked]>
Date: Tue, 01 Oct 2013 16:10:52 -0500

On 10/1/2013 2:24 PM, Y. Richard Yang wrote:
> Hi Sebastian,
>
> Thanks a lot for the always wonderful work!

I was just thinking the same thing :-)

Spencer

---

From: "Y. Richard Yang" <[email-masked]>
Date: Wed, 2 Oct 2013 09:28:01 -0400

Hi Sebatian,

On Tue, Oct 1, 2013 at 4:49 PM, Sebastian Kiesel <[email-masked]>wrote:

> > On Tue, Oct 1, 2013 at 2:33 AM, Sebastian Kiesel <[email-masked]
> >wrote:
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

---

From: "Y. Richard Yang" <[email-masked]>
Date: Wed, 2 Oct 2013 12:15:26 -0400

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-masked]> wrote:

> After the server gets a query, the server first checks the syntax, an
> error happens if the syntax is wrong: E_SYNTAX
>
> The preceding is a simple change in Sec. 8.5.2, and is more extensible.
> How does this sound?
>
> Thanks again!
>
> Richard
>
>
>> Thanks
>> Sebastian
>>
>
>

---

From: Sebastian Kiesel <[email-masked]>
Date: Wed, 2 Oct 2013 22:50:21 +0200

Hi Richard, all,

I think for consistency, it would make sense to rename E_JSON_VALUE_TYPE
to E_INVALID_FIELD_TYPE

Furthermore, we should make clear that the text below the table
is a non-normative illustration how these error codes might be used,
but not a mandatory-to-implement-like-this way of doing sanity checks.

     | E_MISSING_FIELD       | Required JSON field missing               |
     | E_INVALID_FIELD_TYPE  | The type of a JSON field is invalid       |
>    | E_INVALID_FIELD_VALUE | The value of a JSON field is invalid      |

   After an ALTO Server receives a query message, it needs to verify the
   syntactic and semantic validity.  The following paragraphs in this
   section are intended to illustrate the usage of the error codes
   defined above.  Note that the order of the checks is implementation
   specific.

   In the first step after an ALTO Server receives a query, it checks
   the syntax of the query, i.e., whether the JSON structure can be
   parsed, and indicates a syntax error using the error code E_SYNTAX.

>    key in the "meta" field of the response, to indicate the missing

   A query with correct query fields might use a wrong type for a field.
   For example, a request could use a JSONString when a JSONNumber is
   expected. The server indicates such an error using error code
   E_INVALID_FIELD_TYPE.  The server may include the optional "field"
   key in the "meta" field of the response, to indicate the field that
   contains the wrong type.

Thanks
Sebastian

---

From: "Y. Richard Yang" <[email-masked]>
Date: Wed, 2 Oct 2013 17:47:20 -0400

Hi Sebastian,

Thanks a lot. Please see below.
> I think for consistency, it would make sense to rename E_JSON_VALUE_TYPE

In a sense, if a query uses an invalid type (e.g., string but should be
number) when specifying the value of a field, it is an invalid field value
already. But this is a different error (can be caught by syntax without
using semantics). Hence it is good for me.

> but not a mandatory-to-implement-like-this way of doing sanity checks.

Good approach to make clear the non-normative aspect.

> >    encroaches needlessly on implementation techniques.

The new text looks great to me. We will post a new version tonight, unless
we hear objections.

Thanks again!

Richard

---

From: Sebastian Kiesel <[email-masked]>
Date: Thu, 3 Oct 2013 00:04:41 +0200

Hi Richard,

> using semantics). Hence it is good for me.

I think it is important to have a way to indicate invalid (or
unsupported or unexpected) types.

What happens in the future, when we define an extension document that
specifies, say, using AS Numbers instead of IP addresses? This document
will probably contain a mechanism through which a server can indicate
that it supports ASNs. But then, what happens if the server does NOT
announce this capability but the client nonetheless sends such a query?
This query would be completely valid in the sense of the specifications,
except for the fact that the server can't handle it.  Sending "syntax
error", or "invalid value" although the AS number is perfectly valid,
does not seem appropriate to me.

Thanks
Sebastian