Re: [widgets] Comments on Section 5 of the 18-Aug-2009 LCWD of A&E spec

On Wed, Sep 9, 2009 at 10:07 PM, Arthur Barstow <art.barstow@nokia.com> wrote:
> Below are some comments about Sections 5. and 5.1 of the 18-Aug-2009 LCWD of
> the A&E spec:
>
>  <http://www.w3.org/TR/2009/WD-widgets-apis-20090818/>
>
> In general, it seems like Section 5. is more verbose that it needs to be.
>
> -Regards, Art Barstow
>
>
> 1. The following statement is an implementation detail that should be
> removed:
>
> [[
> A user agent must provide a means to flag a key, and its corresponding data,
> as a protected key.
> ]]

Deleted.

> If a UA can implement 6.4 and its subsections, that should be sufficient to
> cover the gist of the above (and if the assertion above is removed, there
> would not be a need to create a test case for it).

Yes, the above is untestable.

> 2. The following is more verbose than it needs to be:
>
> [[
> A user agent must have the ability to create one ore more unique storage
> areas, one for each origin of a widget.
> ]]
>
> It should be shortened to:
>
> [[
> A user agent must be able to create a unique storage areas for each origin
> of a widget.
> ]]
>
> (At a minimum, fix the Typo: "one ore more").

Used your text.

> 3. The following statement doesn't seem necessary given preferences is of
> type Storage; as such, I think it should be removed:
>
> [[
> A user agent must have the ability to directly read and write to the storage
> area (i.e., without needing to make use of the [WebStorage] specification's
> Storage interface) and must  have the ability to delete a storage area.
> ]]

I don't agree. The above gives a storage area the ability to be
populated with config.xml <preference> data without the UA using the
Storage interface. This is important, as events must not be fired
during pre-population.

However, it might be that the above assertion needs to be rewritten to
directly address the <preference> use case (hence making the assertion
more testable). WDYT?

> 4. The use of "arbitrary" doesn't seem appropriate here ("An arbitrary limit
> ..."). If anything needs to be said about this hint to a UA, it seems like
> it should just say "A minimum of 5MB per origin of a widget is recommended."
> There is also a typo at the beginning of the assertion - should be "A user
> agent should limit".

Fixed typo. Used your suggested text:
"A minimum of 5MB per origin of a widget is recommended."

> 5. In the assertion about author scripts, it appears "... ,but must behave
> ..." should be "... and the user agent must behave ...".

Fixed.

> 6. The following assertion is another implementation detail that should be
> removed or made non-normative:
>
> [[
> A user agent should impose their own implementation-specific limits on the
> length of otherwise unconstrained keys and values of a storage area, e.g. to
> prevent denial of service attacks, to guard against running out of memory,
> or to work around platform-specific limitations.
> ]]

The above is a boilerplate "hot potato" assertion, that puts the onus
of securing the implementation on implementers. It's basically there
to protect the WG from people asking "what happens if I try to
store/do something strange". I don't know if we should remove it.

> 7. The three MAY assertions ("may expire", "may prompt", "may allow") don't
> really add anything useful to the spec and as such should be removed or
> turned into n on-normative text (we presumably don't want to create test
> cases for these).

Ok, I've removed them. They are redundant in that WebStorage already
says the above. If you think it will be a problem with WebStorage
also, you should also raise it with Hixie.

See:
http://dev.w3.org/html5/webstorage/#disk-space

> 8. Section 5.1. The following sentence has a couple of problems:
>
> [[
> A protected key is a preference held by the widget preferences variable of
> the configuration defaults table that an author has explicitly flagged as
> "read-only" (denoted by a preference having a readonly value set to true).
> ]]
>
> a. The preferences variable isn't included in the "configuration defaults
> table"

Ah, bah. Ok, this is referring to the big table (configuration
defaults) in the p&c spec. I changed the text to:

"A protected key is a preference held by the widget preferences
variable of the [Widgets-Packaging]'s configuration defaults table "

> b. "widget preferences variable": this text should be changed to "Widget
> object's preferences attribute" and both "Widget" and "preferences" should
> be embedded in <code> tags.

Given the above, this is incorrect.

The way it works it:

1. UA processes foo.wgt's config.xml file.
2. UA stores all <preferences> in the "widget preferences" variable in P&C. See:

http://dev.w3.org/2006/waf/widgets/#widget-preferences

3. UA  takes each author defined preference in widget preferences
(P&C), and puts them in widget.preferences (A&E).
4. UA makes widget.preferences available to scripting environment.

Hopefully that makes more sense.


> c. The link between the Widget object's preferences attribute and the
> <preference> elements in the config document should be made clear.

Ok, obviously I screwed something up.

> It seems like the first sentence above should be something like:
>
> [[
> A protected key is an item in the Widget object's preferences attribute that
> an author has flagged as "read-only" (denoted by a <preference> element as
> defined in [Widgets-Packaging] having a readonly value set to true).
> ]]

That's almost right. But just merely declaring a <preference> in the
config doc does not mean it will appear in widget.preferences . In
other words, we don't want implementers to think that they need to
process config documents themselves. The fact that they already must
implement the P&C spec means that they get all the valid preferences
for free.

Hence also:
"A user agent must only create a protected key in a storage area when
the preferences attribute is initialized." (which links to the section
describing the steps above. See "Initialization of the preferences
Attribute").

Also, because of the recent change to the handling of preferences in
P&C, I've had to update the "Initialization of the preferences
Attribute" section: it no longer deals with overriding key/values that
already exist.



-- 
Marcos Caceres
http://datadriven.com.au

Received on Sunday, 13 September 2009 19:24:39 UTC