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

[Dzonatas Sol <[e-mail]>]

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