[Fiware-middleware] DFKI Thrift-based IDL Proposal

[Dmitri Rubinstein]

Hi all,

as discussed in the last meeting I put here information about our IDL 
proposal. When final document appears online I will copy this text to it.

1. KIARA/DFKI IDL is based on Apache Thrift IDL, with the grammar 
available here:

https://thrift.apache.org/docs/idl

Our grammar is available here:

https://forge.fi-ware.org/plugins/mediawiki/wiki/fi-ware-private/index.php/Middleware_-_KIARA_-_User_and_Programmers_Guide#KIARA_Interface_definition_language

Note: our goal was not to keep a full backwards compatibility with 
Thrift, but to modify a grammar only when necessary. Still technically 
we can be backwards compatible (we can parse already *existing* Thrift 
IDL files), since we avoided to remove any functionality from Thrift 
(only 'oneway' keyword was removed, see below). However, this was not 
tested yet.

2. We did following modifications:

2.1 Base types

2.1.1 Added unsigned types missing in Thrift: u8, u16, u32, u64

2.1.2 Renamed bool to boolean, byte to i8 (signed byte).

'boolean' is used more frequently than 'bool' in other IDLs. We can 
switch back to 'bool' if desired.

'byte' as a signed integer is not consistent with names of other signed 
integers (i16, i32, i64). We can switch back to 'byte' as signed 8-bit 
integer and use 'ubyte' as unsigned 8-bit integer if desired.

A comparison table for basic types for DFKI/KIARA, CORBA, Thrift, etc. 
is here:

https://forge.fi-ware.org/plugins/mediawiki/wiki/fi-ware-private/index.php/Middleware_-_KIARA_-_User_and_Programmers_Guide#Primitive_types

2.2 Annotations

The official Thirft grammar available on the web (see link above) *does 
not* contain flexible annotation syntax. There is an annotation support 
available in the latest Thrift version:

https://github.com/apache/thrift/blob/master/test/AnnotationTest.thrift

However, annotations are limited to key-value pairs and even more 
important: seems that function arguments and return types can't be 
annotated, there are at least no examples.

Instead of using Thrift annotations we decided to introduce a different 
syntax inspired by WebIDL: 
http://www.w3.org/TR/WebIDL/#idl-extended-attributes.

2.2.1 Added syntax for defining custom annotations, similar to structs 
and exceptions:

annotation HTTPPort {
   i32 port = 80
}

2.2.2 Added ability to annotate following entities: services, service 
functions, return types of service functions, arguments of service 
functions. We need this especially for security-related features. For 
example:

namespace * enc

// HTTPPort annotates the 'enc' service with argument 8080
[HTTPPort(8080)]
service enc {

     // Function ping is annotated with Oneway and Encrypted annotations
     // without parameters
     [Oneway, Encrypted]
     void ping()

     // In function saveString Argument s of type string
     // is annotated with annotation OptionallyEncrypted without
     // parameters
     void saveString(string fileName, [OptionallyEncrypted] string s)

     // Return type of function loadString is annotated with
     // annotation OptionallyEncrypted without parameters
     string [OptionallyEncrypted] loadString(string fileName)
}

Also see our documentation: 
https://forge.fi-ware.org/plugins/mediawiki/wiki/fi-ware-private/index.php/Middleware_-_KIARA_-_User_and_Programmers_Guide#Functions_2

2.3 Generic types

Original Thrift IDL supports following predefined container types: 
list<T>, map<T1,T2>, and set<T>. We decided to extend this syntax to 
arbitrary generic types: GenericType<T1, T2, ..., Tn> where Ti can be 
either type or constant. In this way we can support types like bounded 
arrays but still keep backwards compatibility with the original syntax:

array< i32, 2> // bounded array of size 2
array< i32, array< i32, 4> > // two-dimensional array

2.4 Removed Thrift features

We removed 'oneway' keyword from Thrift because we can use annotation 
Oneway:

Original Thrift:

service Test {
   oneway void zip()
}

Our grammar:

service Test {
   [Oneway] void ping()
}

If backwards-compatibility to Thrift is desired we can try to support 
both styles.

2.5 Unused Thrift features

We currently parse but ignore following Thrift features that are missing 
in OMG IDL:

Struct fields can have optional integer identifier.
Struct fields can be 'required' or 'optional'.

2.6 Planned extensions

Thrift does not provide entity like CORBA's 'module'. The namespace 
keyword used by Thrift only allow to specify namespace in the generated 
code. We plan to add module NAME { ... } entity in order to provide 
support for nested IDL namespaces as well as annotations per module.

Best,

Dmitri