Re: [vwrap] informal description of the DSD interface description language
Meadhbh Hamrick <ohmeadhbh@gmail.com> Tue, 05 April 2011 20:11 UTC
Return-Path: <ohmeadhbh@gmail.com>
X-Original-To: vwrap@core3.amsl.com
Delivered-To: vwrap@core3.amsl.com
Received: from localhost (localhost [127.0.0.1]) by core3.amsl.com (Postfix) with ESMTP id B9D8D28C136 for <vwrap@core3.amsl.com>; Tue, 5 Apr 2011 13:11:01 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -3.578
X-Spam-Level:
X-Spam-Status: No, score=-3.578 tagged_above=-999 required=5 tests=[AWL=0.021, BAYES_00=-2.599, RCVD_IN_DNSWL_LOW=-1]
Received: from mail.ietf.org ([64.170.98.32]) by localhost (core3.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id JWh0EGoWOuYL for <vwrap@core3.amsl.com>; Tue, 5 Apr 2011 13:10:50 -0700 (PDT)
Received: from mail-px0-f182.google.com (mail-px0-f182.google.com [209.85.212.182]) by core3.amsl.com (Postfix) with ESMTP id 3EC1A28C12B for <vwrap@ietf.org>; Tue, 5 Apr 2011 13:10:48 -0700 (PDT)
Received: by pxi20 with SMTP id 20so497929pxi.27 for <vwrap@ietf.org>; Tue, 05 Apr 2011 13:12:31 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=domainkey-signature:mime-version:in-reply-to:references:from:date :message-id:subject:to:cc:content-type:content-transfer-encoding; bh=bfWl4wMU3dgJ4ZalvqlufmSNsIVTan5TkY6aHJ2VEnw=; b=ucZxa3nNfBsDXQQiwy78BW0HBABcUxcWXVbnwE+UPvcWFtgPdh9K0DLIN8Q32TBsfz ibVGDaC3mrooqAbC6mRgmz6ljQgHl5DL7yCtyrtXmApKo2Uzfs30t9wcKRgzfWouuwCA Iu6CXu9WhZAgmAf3ScxcL+vxtnW/XnnXD7NkU=
DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=mime-version:in-reply-to:references:from:date:message-id:subject:to :cc:content-type:content-transfer-encoding; b=R9AEwikwy3BMyIwER/+yIoNm8bO9nmavArMYFKU8NmzT7d7u4y7/0cUxi7y2Bz1VYv /PTU+fLyNrdBYKad2mnxk3Fsw0aLm+XehHXgvs65KvHKOksSOPccjPScEPsQyNFC4Sez mntB0ywxIOCU6CT+AkNKvgQqgE+6s2zRrCNcM=
Received: by 10.142.209.12 with SMTP id h12mr106778wfg.91.1302034351409; Tue, 05 Apr 2011 13:12:31 -0700 (PDT)
MIME-Version: 1.0
Received: by 10.68.60.164 with HTTP; Tue, 5 Apr 2011 13:12:10 -0700 (PDT)
In-Reply-To: <4D9B770D.4050207@gmail.com>
References: <AANLkTikEn2OGSe1C6+C2BRjPi9Mrae4gY8nxKNjLxw6S@mail.gmail.com> <4D9B61D4.3000906@gmail.com> <4D9B6861.4030704@gmail.com> <4D9B6D71.5030400@gmail.com> <4D9B6ECE.9000705@gmail.com> <4D9B770D.4050207@gmail.com>
From: Meadhbh Hamrick <ohmeadhbh@gmail.com>
Date: Tue, 05 Apr 2011 13:12:10 -0700
Message-ID: <BANLkTikKD3_Bd5fxNfFxv+hiu87z1VzxrA@mail.gmail.com>
To: Dzonatas Sol <dzonatas@gmail.com>
Content-Type: text/plain; charset="ISO-8859-1"
Content-Transfer-Encoding: quoted-printable
Cc: vwrap@ietf.org
Subject: Re: [vwrap] informal description of the DSD interface description language
X-BeenThere: vwrap@ietf.org
X-Mailman-Version: 2.1.9
Precedence: list
List-Id: Virtual World Region Agent Protocol - IETF working group <vwrap.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/listinfo/vwrap>, <mailto:vwrap-request@ietf.org?subject=unsubscribe>
List-Archive: <http://www.ietf.org/mail-archive/web/vwrap>
List-Post: <mailto:vwrap@ietf.org>
List-Help: <mailto:vwrap-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/vwrap>, <mailto:vwrap-request@ietf.org?subject=subscribe>
X-List-Received-Date: Tue, 05 Apr 2011 20:11:01 -0000
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/ * OhMeadhbh@gmail.com On Tue, Apr 5, 2011 at 1:09 PM, Dzonatas Sol <dzonatas@gmail.com> 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 > >
- [vwrap] informal description of the DSD interface… Meadhbh Hamrick
- Re: [vwrap] informal description of the DSD inter… Dzonatas Sol
- Re: [vwrap] informal description of the DSD inter… Dzonatas Sol
- Re: [vwrap] informal description of the DSD inter… Dzonatas Sol
- Re: [vwrap] informal description of the DSD inter… Dzonatas Sol
- Re: [vwrap] informal description of the DSD inter… Dzonatas Sol
- Re: [vwrap] informal description of the DSD inter… Meadhbh Hamrick
- Re: [vwrap] informal description of the DSD inter… Meadhbh Hamrick