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

[Meadhbh Hamrick <[e-mail]>]

also. in terms of nomenclature... LLSD is the abstract type system
under consideration here. DSD is an extension to LLSD i put together
for my personal projects. ergo... DSD is probably outside the scope of
this effort, LLSD is not.

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



On Tue, Apr 5, 2011 at 1:09 PM, Dzonatas Sol <[e-mail]> wrote:
> Further,
>
> I wanted to give more details about mime-parts used in instead of LLSD array
> for combined formats. To describe mime-parts seems like an overdose:
> xml-org-ietf-vwrap-* where * becomes the public resource. Need to uncompress
> the overall idea we're stuck at here. Mime-parts seems ideal for keep-alive
> and long-poll while LLSD arrays seem ideal otherwise.
>
>
> Dzonatas Sol 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
>
>