Subject: [alto] I suggest adding map-vtag to a few messages

From: Bill Roome <[email-masked]>
Date: Tue, 20 Sep 2011 13:54:14 -0400

A PID name doesn't mean much without the corresponding map-vtag. So I
suggest adding a map-vtag parameter to the following ALTO messages:

1. In Section 7.7.4.1 -- Endpoint Property -- add a "map-vtag" field to
the server's response {7.7.4.1.5}. E.g.

	object {
		JSONString map-vtag;         [OPTIONAL]
		EndpointProps [TypedEndpointAddr]<0..*>;
		...
	} InfoResourceEndpointProperty;

The server supplies that if the client asked for the "pid" property. It's
the tag for those pid names, of course.

2. In Section 7.7.3.2 -- Filtered Cost Map -- add a map-vtag field to the
client's request message {7.7.3.2.3}. Eg,

	object {
		CostMode cost-mode;
		CostType cost-type;
		JSONString map-vtag;          [OPTIONAL]
		JSONString constraints<0..*>; [OPTIONAL]
		PIDFilter pids;               [OPTIONAL]
	} ReqFilteredCostMap;

This is the tag for the network map the client used when selecting those
pids. If that doesn't match the current tag, then the pid definitions have
changed substantially, and the pid names aren't what the client thinks
they are. Hence the server should reject the request. This means adding a
new error code to {7.4.3}, say E_INVALID_MAP_VTAG.

The client can omit the vtag if the request doesn't have any pid names.

	- Bill Roome

---

From: Richard Alimi <[email-masked]>
Date: Wed, 21 Sep 2011 08:46:15 -0700

Hi Bill,

I do think your proposal would suffice, but I think it would be good
to look at how this relates to how we do this with the Cost Map
already. For example, the current mode is that when you ask for the
full Cost Map, the server tells you the version tag. If it doesn't
match the Network Map you've already got, then you need to request a
new Network Map.  Shouldn't the same work for Filtered Cost Maps and
Endpoint Properties*?

If that doesn't suffice and we really wanted to do this the REST-ful
way, the right solution would probably be to have the server return
the response (which includes the map-vtag), but let it also return a
URI for the Network Map that provides information on those PIDs
(presumably with the correct vtag).  Removing explicit versioning
information from requests I think is something that being REST-ful
lets us avoid.

* That said.. endpoint property responses with PIDs need to return
their map-vtag (regardless of the outcome of this discussion).  So
noted. :)

Rich

On Tue, Sep 20, 2011 at 10:54 AM, Bill Roome <[email-masked]> wrote:
> _______________________________________________
> alto mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/alto
>

---

From: Bill Roome <[email-masked]>
Date: Wed, 21 Sep 2011 12:46:46 -0400

>new Network Map.  Shouldn't the same work for Filtered Cost Maps and

There's a significant difference. For the full map request, the client
doesn't give PID names. After the client gets the cost map, the client can
issue a network map request to find out what those PIDs mean.

But with a filtered request, the client asks about specific PIDs. That
implies the client knows what endpoints are in those PIDs. If the network
map has changed, the costs might be meaningless. Or those PID names might
not even exist any more.

So I think that whenever a client gives PID names to the server (which is
inherently in a POST request), the client must also give the vtag for the
map from which it got those PIDs. The server rejects the request if that's
stale.

Otherwise we'll have to rely on the client verifying that the vtag in the
filtered cost map response matches the vtag in the client's copy of the
network map. If not, the client must get the revised map, figure out the
new PID names, and if they're different, send a new cost map request. A
client can certainly do that, but I'm afraid many will forget.

>(presumably with the correct vtag).

Do you mean the URI for the full network map? That's easy enough, although
the client can just as easily get that from the resource directory.

Or did you mean a URI that only gives the definitions of the PIDs in the
client's request? That would be a lot messier to implement. The filtered
cost map service is a post-mode request, so the server can't create a
restful uri for it.

>Removing explicit versioning

Okay, I'm afraid I don't understand that. Why would adding a vtag
parameter to the filtered map request make it non-rest-ful?

Here's the way I look at it. Whenever the vtag changes, the PID
definitions change. So a PID name isn't fixed or absolute; its definition
depends on some hidden state. That means simple PID names are
non-rest-ful, doesn¹t it? A "rest-ful" PID name would have to be qualified
with the vtag -- say 'vtag/PID'. A name like that is invarient -- the CIDR
definition never changes. So it seems to me that adding a vtag parameter
to the request would make the request rest-ful, when it wasn't rest-ful
before.

---

From: Richard Alimi <[email-masked]>
Date: Wed, 21 Sep 2011 10:36:17 -0700

> map has changed, the costs might be meaningless. Or those PID names might

Right - there should be handling in the existing protocol for what
happens with PIDs that no longer exist (they are ignored). But the
rest of your argument still stands...

> client can certainly do that, but I'm afraid many will forget.

I'd be interested to hear others' opinions here, but I'll note a
couple of additional things:

(1) In the model you propose, this is basically turning what is today
a "soft failure" condition where the client gets partial and perhaps
older information back (and is given the opportunity to immediately
detect it and correct it) into a "hard failure" condition, where the
client gets no information at all.
(2) Maybe its a philosophical difference, but I sort of assume that
clients parsing maps understand what the version tag means (since it
is communicated as a sibling to the cost map and cost type, and not
hidden anywhere).  Do you think this is a matter of protecting clients
from not obeying the protocol? Or something else?

> the client can just as easily get that from the resource directory.

Agree - but this gives the server the ability to provide a different
URI than what is in the directory, perhaps one that explicitly refers
to the relevant vtag.  I mentioned this as a more general mechanism
that could solve the problem without adding a specific parameter to
the request.

> cost map service is a post-mode request, so the server can't create a

Agree that that would be messier :) It isn't what I intended to convey.

> to the request would make the request rest-ful, when it wasn't rest-ful

Okay - I didn't mean to convey that what you proposed wasn't
"rest-ful" and I dont want to get bogged down into the religious
argument :) I only meant to imply that being REST-ful (and passing
around links) gives us an additional/alternate way.

Rich

---

From: Richard Alimi <[email-masked]>
Date: Wed, 21 Sep 2011 10:45:40 -0700

> a "soft failure" condition where the client gets partial and perhaps

Small but important correction:
".. the client may apply partial and perhaps..."

---

From: Bill Roome <[email-masked]>
Date: Wed, 21 Sep 2011 14:15:17 -0400

>client gets no information at all.

Ah! But I claim that the returned information could be utterly useless --
and the client can't tell unless the client re-gets the network map.

Specific example: A client asks for the costs from PID1 to PID2 and PID3,
because the client's IP address is in PID1. Now suppose the map changes
and the client is no longer in PID1. Sure, the client gets information
back, but it's irrelevant and misleading.

>from not obeying the protocol? Or something else?

Yup, it's philosophy -- I think the server should protect the client from
a class of potential errors.

The alternative is to say in {7.7.3.2} that the client must verify that
the vtag in the response matches the vtag in the map it used to select
those PIDs. If not, the client must re-get the map (or at least those
PIDs) and verify that they haven't changed.

	- Bill Roome

---

From: Richard Alimi <[email-masked]>
Date: Wed, 21 Sep 2011 11:35:54 -0700

> back, but it's irrelevant and misleading.

Right - so as a client, I could immediately detect that case, store
the retrieved information, and then update the network map. That would
be in comparison to getting an error, going to get a new network map,
then repeating the request.

> PIDs) and verify that they haven't changed.

Yes - at a minimum we can add cautionary text, but it'd be interesting
to see what others say here too.

Thanks!
Rich