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

[Dzonatas Sol <[e-mail]>]

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