Re: [vwrap] informal description of the DSD interface description language

[Meadhbh Hamrick <[e-mail]>]

actually, you can find more notes on DSD at
http://blog.meadhbh.org/2010/07/abstract-resource-definitions-vs-llidl.html

though i am likely abandoning it since there's no telling what's
happening with this group. if this group continues, i'll be happy to
submit it as a draft here. if this group disbands, i'll likely submit
it as an informational individual submission to the RFC editor so
existing sites that use DSD (sl8.us, etc.) can take the X- off their
content type headers.

-cheers
-meadhbh
--
meadhbh hamrick * it's pronounced "maeve"
@OhMeadhbh * http://meadhbh.org/ * [e-mail]



On Tue, Apr 5, 2011 at 12:34 PM, Dzonatas Sol <[e-mail]> wrote:
> Let me reformat...  there were extra chars (processed):
>
> Re: "bust mode" or "combined"
>
> See the syntax I used here:
> http://wiki.secondlife.com/wiki/User:Dzonatas_Sol/SNOW-375_Resources/Asset
>
> I used the the curly brackets {} with ellipses to show what kind of data can
> be combine as an array in LLSD. Here note that the UUID moves from the
> RESOURCE into the array as the individual items are combined, such that
> indivual requests for:
>
> /Asset/Notecard/00000000-0000-0000-0000-000000000001
> /Asset/Notecard/00000000-0000-0000-0000-000000000002
> /Asset/Notecard/00000000-0000-0000-0000-000000000003
> /Asset/Notecard/00000000-0000-0000-0000-000000000004
>
> become
>
> /Asset/Notecard/s
> {
> 00000000-0000-0000-0000-000000000001,
> 00000000-0000-0000-0000-000000000002,
> 00000000-0000-0000-0000-000000000003,
> 00000000-0000-0000-0000-000000000004
> }
>
> The combined reply may look like:
>
> /Asset/Notecard/s
> {
> 00000000-0000-0000-0000-000000000001, { asset-data... }
> 00000000-0000-0000-0000-000000000002, { asset-data... }
> 00000000-0000-0000-0000-000000000003, { asset-data... }
> 00000000-0000-0000-0000-000000000004  { asset-data... }
> }
>
> Handling assets not immediately available are easy, I just stick the
> individual response codes in the array instead of expect it as an httpcode.
>
> Dzonatas Sol wrote:
>>
>> Dzonatas Sol wrote:
>>>
>>> There are two(/three) significant touches I made:
>>>
>>> First, burst mode. Already as people upgrade to capabilities rather than
>>> the older UDP style we can see they complain about bottlenecks due to
>>> individual requests being made. This is more of fault of the implementators
>>> not doing full ReST rather than the limits of capabilities. I denote "burst
>>> mode" to make sure full ReST is being implemented.  This is where RESOURCES
>>> & INTERFACES keep the very basic object oriented message paradigm. Then
>>> capabilities then can become used for specific individual queries to
>>> combined multiple resource queries. This alleviates the individual
>>> connections per item into the non-issue bit-bucket. The only new issue with
>>> "burst mode" is limits on how many items can be combined (length of overall
>>> body and parts).
>>>
>>> Second, public resources. The significance I put on "resources" is that
>>> these are the public names being referred to for any such related message
>>> and/or method. Already implemented are the private version of these
>>> resources. Maybe there needs to be some syntax to note that the resources
>>> appear as something else under specific conditions. The current private URIs
>>> are just a digest of given capabilities present (used by lookup tables).
>>> Internally, only the public resources are of need, yet the private URI may
>>> contain something in regards to the basic object oriented message paradigm.
>>> It's not that complicated once one separates the ReST paradigm from HTTP
>>> methods and implements the full ReST paradigm internally. When the
>>> implementator relies on HTTP as the queue, then they don't have a true ReST
>>> paradigm, only something compatible (for quick implementation).
>>>
>>> Third, private resources, as above and already implemented by LL
>>> (stateless). We haven't got into stateful tranfer connections. *sigh* These
>>> would be ideal for the keep-alive, long-poll, and bust mode options.
>>>
>>>
>>> Dzonatas Sol wrote:
>>>>
>>>> Some notes... in line...
>>>>
>>>> Meadhbh Hamrick wrote:
>>>>>
>>>>> hey peeps, it shouldn't be shocking to anyone i'm not a big fan of
>>>>> lentczner's "little" interface description language, llidl. while it can be
>>>>> argued it's "condensed" format is easy enough to use, once mastered, i
>>>>> prefer something mildly more expressive. when i was working on the last
>>>>> version of the LLSD draft, i solicited comments from several implementers
>>>>> inside and outside Linden, and they all said the same thing: "LLIDL is cool
>>>>> enough, but it looks like line noise if you don't know what you're looking
>>>>> at."
>>>>>
>>>>> i came up with the following interface description language to address
>>>>> the "looks like line noise" critique. this is the IDL that's going in the
>>>>> DSD draft, since that's what we're using at sl8.us <http://sl8.us> and
>>>>> various sensor projects that are using DSD. i'm assuming you've read and
>>>>> understand the LLIDL section of the most recent type system draft.
>>>>>
>>>>> again, i have no idea if this will be relevant since no one's stepped
>>>>> up to be an document author for future revisions of this group's docs or an
>>>>> editor to re-draft a new charter. but on the off chance people do this and
>>>>> still want to work on the type system, these are the changes recommended by
>>>>> several LLIDL users and implementers.
>>>>
>>>> Be sure to see review these to see how I based off LLIDL:
>>>>
>>>> http://wiki.secondlife.com/wiki/User:Dzonatas_Sol/SNOW-375#Queries_.26_Type_System
>>>>
>>>> http://wiki.secondlife.com/wiki/User:Dzonatas_Sol/SNOW-375_Resources/Asset
>>>>
>>>> http://wiki.secondlife.com/wiki/User:Dzonatas_Sol/SNOW-375_Resources/Interface
>>>> (and others there)
>>>>
>>>> Note that I used more of what is in regards to ReST than only LLIDL.
>>>>
>>>>>
>>>>> *item 0 : disentangling resources from interfaces.*
>>>>>
>>>>> LLIDL sort of conflated a resource (something to be accessed) with the
>>>>> method of accessing it. there was no way to "officially" define a "resource"
>>>>> independent of the semantics to access it. DSD says that RESOURCEs are just
>>>>> data definitions. INTERFACEs define how they're used.
>>>>
>>>> As I see "resource", it manly is untranslated to any particalar
>>>> implementation. Some still think there is an obvious implementation due to
>>>> common resources being used by HTTP. I think you have some like C#'s
>>>> interface in mind?
>>>>
>>>>
>>>>>
>>>>> *item 1 : say good-bye to the di-graphs.*
>>>>>
>>>>> several people noted that LLIDL, at first glance, looks like line
>>>>> noise. this is because of the use of digraphs to represent messaging
>>>>> semantics. cast your memory back to the LLIDL resource description for the
>>>>> seed cap:
>>>>>
>>>>>    %% seed
>>>>>      -> { capabilities: [ string, ... ] }
>>>>>      <- { capabilities: { $: uri } }
>>>>>
>>>>>
>>>>> the '%%' digraph means 'start of resource description'. the '->' means
>>>>> 'this is what i'm going to send you' and the '<-' digraph means 'i expect
>>>>> you to send me this back'.
>>>>>
>>>>> instead of digraphs, the DSD resource description language uses the
>>>>> keyword "RESOURCE" to begin a resource. it also terminates the resource
>>>>> definition with a semi colon. so a resource declaration would look something
>>>>> like this:
>>>>>
>>>>> RESOURCE <resource name> [resource definition] ;
>>>>>
>>>>> resource DEFINITIONs look more or less like they used to. for example,
>>>>> here's a RESOURCE definition for a typical error response:
>>>>>
>>>>>    # Resource description for a typical error resource
>>>>>    RESOURCE error_simple {
>>>>>       success     : false,    # clients check the success element to
>>>>>    see if there was an error
>>>>>       errno       : integer,  # this is a numeric code representing
>>>>>    the error
>>>>>       error       : string,   # this is a text description of the error
>>>>>       description : uri       # this is a URL that points to a HTML
>>>>>    web page describing the error
>>>>>    };
>>>>>
>>>>
>>>> Think we discussed this before, which I said wasn't much of the worry
>>>> since the what is pivotal is more significant. That said, however, be sure
>>>> to keep in mind that anything like digraphs make it easier to use
>>>> non-English only keywords.
>>>>
>>>> We seem to agree in structure.
>>>>
>>>>
>>>>
>>>>>
>>>>> *item 2 : the use of type literals instead of type names*
>>>>>
>>>>> in the example above, we used 'false' instead of 'boolean' as the type
>>>>> definition for the 'success' element of the error resource. DSD resource
>>>>> definitions can use type literals to imply that the element should exist,
>>>>> and should have a specific value. so if you wanted to define a resource that
>>>>> represented the origin of a 3d space, you could use:
>>>>>
>>>>>    # Point in a 3D rectangular space     RESOURCE cartesian_point [
>>>>>       real,  # x coordinate
>>>>>       real,  # y coordinate
>>>>>       real   # z coordinate
>>>>>    ];
>>>>>
>>>>>    # Origin of a rectangular (cartesian) space
>>>>>    RESOURCE cartesian_origin [ 0.0, 0.0, 0.0 ];
>>>>>
>>>>
>>>> Good idea, I'm just not quite sure if it is so obvious in practice.
>>>>
>>>>
>>>>>
>>>>> *item 3 : type specifiers use the same names as the elements inside the
>>>>> XML serialization.*
>>>>>
>>>>> instead of using "int", we use "integer." ditto for other types. so the
>>>>> resource definition. here's a resource definition for something with an
>>>>> integer in it:
>>>>>
>>>>>    # Random resource definition of a map with an integer in it
>>>>>    RESOURCE whatever {
>>>>>       element : integer
>>>>>    };
>>>>>
>>>>
>>>> This is made obvious by the default use of LLSD, still. Notice SNOW-375
>>>> I did have a few extras for optional fields and proprietary fields. We know
>>>> they are there, but probably won't have an public definition of such
>>>> structures. Guess we need that tidbit formalized.
>>>>
>>>>
>>>>>
>>>>> *item 4 : DSD variant declarations don't suck for beginners*
>>>>>
>>>>> i always thought repeated '&' definitions to denote variants was sort
>>>>> of snobbish. it makes sense to peeps who've sat through classes on regular
>>>>> grammars and ABNF, but i wouldn't mind it too much if someone with a basic
>>>>> understanding of procedural coding could understand what was going on. so i
>>>>> came up with the VARIANT keyword. it looks like this:
>>>>>
>>>>> VARIANT <variant-name> : <variant-type> { <variants> }
>>>>>
>>>>> so here's an example:
>>>>>
>>>>> # Enhanced Error resource
>>>>>
>>>>>    RESOURCE error_enhanced VARIANT error_type : string {
>>>>>        'number' : {
>>>>>          success : false,
>>>>>          errno : integer
>>>>>       },
>>>>>       'string' : {
>>>>>          success : false,
>>>>>          error : string
>>>>>       },
>>>>>       'url' : {
>>>>>          success : false,
>>>>>          description : uri
>>>>>       }
>>>>>    };
>>>>>
>>>>>
>>>>> what this means is that the "error_enhanced" resource has three valid
>>>>> forms, that look like:
>>>>>
>>>>>    RESOURCE error_enhanced {
>>>>>       error_type : 'number',
>>>>>       success : false,
>>>>>       errno : integer
>>>>>    };
>>>>>
>>>>>    RESOURCE error_enhanced {
>>>>>       error_type : 'string',
>>>>>       success : false,
>>>>>       error : string
>>>>>    }
>>>>>
>>>>>    RESOURCE error_enhanced {
>>>>>       error_type : 'url',
>>>>>       success : false,
>>>>>       description : uri
>>>>>    }
>>>>>
>>>>>
>>>>> so the <variant name> shows up as an element in each of the valid forms
>>>>> as an literal element of type <variant-type>.
>>>>
>>>> Did I find any significant use for such? I mean is there somewhere in
>>>> specific that that variant structure is more helpful than what I used? I
>>>> think as we get into more specific usage and documentation of that usage we
>>>> do need simplified ways makes some redundancy obvious. I just used wiki
>>>> markup for that for now, I think.
>>>>
>>>>
>>>>>
>>>>> *item 5 : say good by to HTTP verbs.*
>>>>>
>>>>> LLIDL as specified is pretty much intertwined with HTTP. many people
>>>>> thought that was a bad idea. In creating an interface, DSD uses five
>>>>> abstract "interaction semantics": CREATE, READ, UPDATE, DELETE and EVENT.
>>>>>
>>>>> the first four do what you expect them to do while the last one
>>>>> describes the form or "shape" of an unsolicited message coming from the
>>>>> event queue.
>>>>>
>>>>> so if you wanted to login, you might use the following interface
>>>>>
>>>>>    INTERFACE CREATE session_factory {
>>>>>       username : string,
>>>>>       secret : binary
>>>>>    } RESPONSE VARIANT success : boolean {
>>>>>       false : {
>>>>>          errno : integer,
>>>>>          err : string,
>>>>>          description : uri
>>>>>       },
>>>>>       true : {
>>>>>          seed : uri
>>>>>       }
>>>>>    };
>>>>>
>>>>>
>>>>> or, you could do the following:
>>>>>
>>>>>    RESOURCE error {
>>>>>       errno : integer,
>>>>>       err : string,
>>>>>       description : uri
>>>>>    };
>>>>>
>>>>>    INTERFACE CREATE session_factory {
>>>>>       username : string,
>>>>>       secret : binary
>>>>>    } RESPONSE VARIANT success : boolean {
>>>>>       false : error,
>>>>>       true : {
>>>>>          seed : uri
>>>>>       }
>>>>>    };
>>>>>
>>>>>
>>>>> so anyway, i'm writing up this stuff in the DSD type system draft. feel
>>>>> free to comment. as things stand, if VWRAP continues as a working group,
>>>>> i'll integrate your comments on the draft. if not, i'll modify the draft so
>>>>> as to remain compatibility with existing DSD implementations and publish it
>>>>> a an individual / informational draft for the purpose of registering the
>>>>> mime types.
>>>>
>>>> As long as usage doesn't fall out of ReST than it'll work. Remember that
>>>> ReST doesn't have to use HTTP. If you see my implementation, there is the
>>>> ReST queue being full of tasks and part of those task relate to HTTP
>>>> methods. People don't seem to often split ReST queries as different than
>>>> HTTP verbs, but I do. I guess that is like resource/interface differences.
>>>>
>>>> I thought I saw another submitted document to review, yet couldn't find
>>>> it. Was there a newer version?
>>>>
>>>>
>>>>
>>>
>>>
>>
>>
>
>
> --
> --- https://twitter.com/Dzonatas_Sol ---
> Web Development, Software Engineering, Virtual Reality, Consultant
>
>