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

[Dzonatas Sol <[e-mail]>]

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