Subject: feedback on draft-ietf-opes-end-comm-02

From: Alex Rousskov <[email-masked]>
Date: Wed, 1 Oct 2003 10:37:30 -0600 (MDT)

Abbie,

	Here is my comments on the latest Communication draft,
draft-ietf-opes-end-comm-02.

	The overall structure and flow of the document improved
significantly. Thank you!

	There are several major flaws and few minor bugs remaining. In
this email, I will try to concentrate on major flaws:

	* Compliance subjects: The number of things for which
	there is at least one MUST/SHOULD/MAY requirement, is
	too large. Sometimes it is even not clear what subject
	a requirement applies to. Please make sure that all
	requirements apply to an OPES entity, an OPES system,
	or a application binding specification. If you feel
	that other compliance subjects are needed, let's
	discuss this. Please add a "Compliance Considerations"
	section.

	* Misplaced compliance requirements: Please avoid
	sprinkling informative text and definitions(!) with
	MUST/SHOULD/MAYs. Let's try to move all requirements
	for OPES entities to the corresponding sections of
	the draft.

	* Multiple definitions: Several concepts have multiple
	definitions. There must be one definition, optionally
	followed by examples and rationale.

	* Vague requirements: Please check that every
	MUST/SHOULD/MAY uses no undefined or unnecessary
	adjectives. If a particular requirement cannot be
	formulated without a vague adjective, perhaps it should
	not be a requirement. This may seem like a lot of work
	but (a) it is an important spec quality aspect and
	(b) you are likely to end up with fewer requirements
	after the above flaws are addressed.

	* Vague definitions: same as vague requirements but
	as applied to definitions. Avoid adjectives and
	implied clauses in a definition.

	* Implied definitions: "Foo is Bar" is a definition.
	"Foo can be Bar", "Foo describes Bar", etc. are not.
	MUST/SHOULD/MAY keywords identify requirements.
	You may want to use "Definition:" prefix to identify
	definitions. If you do not like the prefix, please
	make sure that all definition-looking sentences are
	either clearly marked as definitions or rephrased
	to avoid misleading looks.

	* Bypass: the draft does not mention bypass mechanisms
	but should.

Below, I will point to specific places exhibiting the above flaws.
Your original text is quoted using "> ". I will use flaw headings from
the above list to shorten notes when possible.

> This memo documents tracing requirements for Open Pluggable Edge
> Services (OPES).

Bypass.

> The execution of such services is governed by a set of rules
> installed on the OPES processor. ...

The above paragraph seem to have very little to do with tracing.
Do we need to repeat architecture description here?

> The work specify the requirements for providing tracing functionality
> for the OPES architecture [8]. This document specifies tracing
> mechanisms that the OPES architecture could provide that enable data
> provider application to detect inappropriate client centric actions
> by OPES entities.

So which is it? "Requirements for providing tracing functionality"
or "tracing mechanisms"?

> This document specifies tracing
> mechanisms that the OPES architecture could provide that enable data
> provider application to detect inappropriate client centric actions
> by OPES entities.

What about inappropriate server-centric actions? Are tracing
mechanisms symmetric?

> This work investigates this possibility and discusses possible
> methods that could be used to detect faulty OPES processors or
> callout servers by end points in an OPES flow.

Let's be more firm/specific: "This document specifies ... for ..."
Avoid "possibilities", "investigations", and "coulds".

> The document is organized as follows: Section 2 defines OPES Domain
> ...

Delete the above paragraph. It is an [incorrect] repetition of the
table of contents. This is not a research paper without a TOC where
such paragraphs are common and useful.

> This sections clarifies the terms OPES system and OPES Domain [8].

[8], the Architecture draft you are referring to does not define OPES
system and OPES Domain. Are you implying that the Architecture draft
should be fixed to include such definitions? If yes, please place an
XXX note so that we do not forget to change the Architecture draft and
remove system/domain definitions from Communications draft when the
Architecture draft is updated. If you are not implying anything, then
please remove the above reference to [8].

> An OPES domain describes the collection of OPES entities that a
> single provider operates.

Implied definition?
	An OPES domain is ...

I failed to find much text that actually uses OPES Domain. I can only
see two requirements (and I do not understand their rationale). If
those requirements are gone, I would suggest removing OPES Domain
until is needed. (OPES Domain is different from OPES trust domain,
right?).

> An OPES domain describes the collection of OPES entities that a
> single provider operates.

Please give an example. It is not clear what "single provider
operates" means because it is not clear what is a "provider" in this
context and what it means to "operate" an OPES entity.

> OPES domains can be based on trust or other operational boundaries.

Is "trust" an operational boundary? What is an "operational boundary"?

> All entities of an "OPES Domain" MUST be in the same trust domain.

Compliance subjects. Does not your OPES Domain definition above
imply the "same trust domain" clause?

> An OPES system consists of a limited set of OPES entities, parts of a
> single or of multiple OPES domains, organized by (or on behalf) of
> either a data provider application or a data consumer application to
> perform authorized services on a given application message.

Vague definition.

> An OPES system can be formed in a recursive manner. An OPES system
> can start ...

Implied definition? Multiple definitions for OPES system?

> Each OPES entity in an OPES system MUST be directly addressable at
> the IP level by a data consumer application.

Misplaced compliance requirement. Also, is this requirement really in
Communications draft scope?

> An OPES domain MUST not be an OPES sub-system.

Compliance subject.

Also, what is an OPES sub-system? A subset of OPES entities within an
OPES System? If yes, then does not Figure 1 show OPES domains that are
OPES sub-systems?

> An OPES domain MUST
> require external resources to provide services.

Compliance subject. Or is it a part of an implied definition?

> A data consumer
> application MUST be able to receive tracing information on per
> message basis

Compliance subject.

> Tracing is defined as the inclusion of
> necessary information within a message in an OPES flow that could be
and
> o  OPES tracing: the process of including, manipulating, and
>    interpreting an OPES trace in an OPES System.

Multiple definitions.

> To emphasize, the above definition means that OPES tracing SHOULD be
> performed on per message basis.

Compliance subject.

> In an OPES System the task of providing tracing information, must
> take into account the following considerations:

Assuming the above "must" is a "MUST", this is a Compliance subject
flaw. The subject of the above must is the "task of providing tracing
information"!

> Tracing information MUST be able to provide a data consumer
> application with useful information without tracing the exact OPES
> Processor or callout servers that adapted the data.

Compliance subject. Vague requirement.

> o  An OPES service SHOULD add its entry to the trace.

I believe this should be a MAY. Rationale: Many OPES services are
message-agnostic and operate on message content or parts. Such
services cannot manipulate message headers and, hence, cannot trace
themselves. Since an ideal OPES service is usually message-agnostic,
it seems inappropriate to place a SHOULD-level requirement that an
ideal implementation would necessarily violate.

>    For example, an OPES processor may add or
>    remove callout service entries in order to manage the size of a
>    trace.

Consider making this a separate paragraph, with an appropriate intro
phrase. Let's not clobber the requirements list.

> trace. Other considerations include:

Is this still a part of a "For example" clause?

>    *  The OPES processor MAY have a fixed configuration that enable
>       it to respond to tracing inquires.

Unclear. Needs more details/examples? Is this (and others in the same
list) an example or a MAY-level requirement? They look like examples
to me. "A proxy MAY cache" is a requirement. "A proxy can keep its
cache in RAM" is an example or similar informative text. In our scope,
if something does not effect traffic on the wire, it is most likely
NOT a requirement.

> From an OPES context, a good tracing approach is similar to a trouble
> ticket ready for submission to a known address.

The trouble ticket analogy is good. Please rephrase so that it is
clear that the "known address" is _included_ in (a part of) the
"ticket" in our case.

> 3.2 Requirements for Information Related to Traceable Entities?

Is question mark at the end intentional?
Compliance subject.

> The requirements for information as related to entities that are
> traceable in an OPES flow are:

Compliance subject.
What level (MUST/SHOULD/MAY) are these requirements.

> the concept of an "OPES system"
> being traceable, requires that each OPES processor MUST support
> tracing.

The concept most certainly does not require that.

> An OPES provider can have its private policy for trace information,
> but it MUST support tracing mechanisms and it MUST reveal its
> policy.

Compliance subject.

> o  Each OPES processor MUST belong to a single OPES Domain.
> o  Each OPES processor MUST have a Unique Identity in that Domain.

Why?

> In an OPES system, it is the task of an OPES processor to add trace
> records to application messages. In this case, the callout servers
> that uses the OCP protocol [5] are not affected by tracing
> requirements.

And yet, we say that callout servers SHOULD add trace records.

> In order for an OCP protocol to be tracing neutral, an OPES
> processor in an OPES system MUST be able to meet the following
> requirements:

Why is Communication draft concerned with OCP protocol neutrality?

> o  Callout services adapt payload regardless of the application
>    protocol in use and leave header adjustment to OPES processor.

This is not a requirement.

> o  OPES processor SHOULD be able  to trace it's own invocation and
>    service(s) execution since they understand the application
>    protocol.

Misplaced compliance requirement.

> o  Callout servers  MAY be able to add their own OPES trace records
>    to application level messages.

Conflicts with an earlier SHOULD?

> A trust domain may include several OPES systems.

By definition of an OPES system, it is not possible. OPES system
includes everybody that trusts somebody within that system.

> Within a trust domain, there MUST be at least support for one trace
> entry per OPES system.

Compliance subject.

> Entities outside of that system may or may not see any traces,
> depending on domain policies or configuration. For example, if an
> OPES system is on the content provider "side", end-users are not
> guaranteed any traces. If an OPES system is working inside end-user
> domain, the origin server is not guaranteed any traces related to
> user requests.

While I agree with the realism of the above statement, it goes against
IAB wishes, does it not? We already require on a MUST level that the
above does not happen.

> In order to support tracing, the following aspects must be addressed:
> ...

Misplaced compliance requirements.
Compliance subjects.

(this applies pretty much to the whole section 7 as it repeats many
 requirements and introduces many requirements for unclear or
 inappropriate subjects)

> 8. Tracing Examples

Since all current examples are HTTP-specific, would it be better to
keep them in the HTTP Adaptation draft? Is it a good idea to repeat
more than one example from another draft?

If you keep the examples, please update 1995 dates used (see latest
HTTP adaptation draft or use any recent date of your choice).

> 9. Optional Notification

The text of this section repeats IAB draft rant. Should we keep the
rant in IAB draft and just leave one short paragraph with a single
example from the HTTP Adaptation draft?

HTH,

Alex.