While working on (https://github.com/chuyskywalker/reverse-php-barrister-idl) I came across the dilemma that, within interfaces, there is no room for comments on parameters and return values. As an example, in PHP:

/**
 * Manage Page Content on site
 */
class Content {

    /**
     * Add a new page to the system.
     *
     * createdTime, updatedTime, version, and id are automatically set upon creation.
     *
     * @param string $authorId
     * @param string $title
     * @param string $body
     * @param string[] $tags
     * @param PageCategory $category
     *
     * @return string The generated page id
     */
    public function addPage($authorId, $title, $body, array $tags, PageCategory $category) {}

}

Corresponding IDL:

// Manage Page Content on site
interface Content {

    // Add a new page to the system.
    //
    // createdTime, updatedTime, version, and id are automatically set upon creation.
    addPage(authorId string, title string, body string, tags []string, category PageCategory) string

}

Nearly everything in the PHP snippet is codified within the IDL/JSON except for the return value explanation and comments on parameters.

The comment on return value is probably more important as params should generally be pretty clear via their variable names.

Not really sure how the IDL would be composed to account for these though, but having them would help complete the IDL translation layer.

As described in the official specification, JSON-RPC 2.0 does support Notifications.

A Notification is a Request object without an "id" member. A Request object that is a Notification signifies the Client's lack of interest in the corresponding Response object, and as such no Response object needs to be returned to the client. The Server MUST NOT reply to a Notification, including those that are within a batch request.

Notifications are not confirmable by definition, since they do not have a Response object to be returned. As such, the Client would not be aware of any errors (like e.g. "Invalid params","Internal error").

In fact, Barrister does not support notifications, but it should.

@coopernurse is there any reason about this choice?

/cc @devalecs and @brunobellissimo who are working with me using barrister

The conformance suite is run by this script:

https://github.com/coopernurse/barrister/blob/master/run_tests.sh

The basic idea is that each language binding provides two programs (client and server). The bindings are run against each other pair-wise (python client to Go server, ruby client to Go server, etc). Each repo has the client/server code for that language. For example, with Go:

https://github.com/coopernurse/barrister-go/tree/master/conform

The issue with the current implementation is pretty simple - you have to have all the language bindings installed in the right place, and some of them (e.g. PHP) have some external dependencies. With Docker we would probably just make an image per language (e.g. barrister/conform-go, barrister/conform-ruby) that has the client/server programs for that language.

I've used TravisCI for testing libraries, but in this case we'd need to start multiple containers and then probably a 3rd container that actually coordinates the test and verifies the results.

This ticket is a placeholder to discuss the switch to Docker and figure out a general approach. We can create more concrete issues with dev tasks once we have a rough plan in place. This project will impact all the language binding repos.

doc: https://thrift.apache.org/docs/types#containers

Would be nice to get list, setand map

It'd be nice to have composable interfaces like this:

interface Base {
   name() string
   features() []string
}

interface Special extends Base {
   featureA() string
   featureB() string
}

I tried to compile an IDL without any return type and it breaks:

plex.errors.UnrecognizedInput: 'None', line 3, char 16: Token not recognised in state 'type-opts'
Error loading IDL from STDIN: unexpected end of JSON input

Is it supported? If not, is there any reason to not support it? I think that empty result array is a valid response for JSONRPC request, right?

Having the timestamp in the parsed IDL (and a similar one in the autogenerated Go code) makes it impossible to generate same binaries twice from the same code.

It also adds unnecessary complexity of merging if two people have regenerated the code from IDLs in the same repository.

Is there any benefit of having that timestamp included in the parsed IDL?

Sorry, but it's not clear to me from the web site (or README) just what problem Barrister solves.

It appears to be a sort of language-independent way of writing specs (in place of something like Rspec or Cucumber) for APIs. If you've got RESTful applications or apps that use remote procedure calls, it appears you would use this to help ensure everything is returning the correct data type.

If this is incorrect or incomplete, please explain or elaborate.

If this is correct, could you explain why anyone would prefer this over much more flexible options (that can easily verify that not only is the type correct, but so is the data) like Rspec (or whatever option is available for the language you're using). If language-independence is the only gain, what makes the loss of flexibility worthwhile?

The README says "Barrister lets you write well documented services that can be consumed from a variety of languages", but that doesn't really make it much clearer to me than the web site. Is this about allowing applications to read the IDL and "figure out" whether they want to consume the app? (Seems like the AI involved is much more complicated than any problem it might solve.) Is this about just generating docs for your APIs? It seems that it must be about more than that.

Forgive me if I'm being a bit thick, but I'm guessing if I'm not getting it there might other potentially interested developers who don't get it either, and who pass over it without asking any questions.

Thanks!

I'd like to be able to define the error codes in the IDL, and once there, it would be cool to automatically build the errors with those codes.

For example, if I define in myservice.idl

error NotFound = 1

In case of Go code I would have automatically generated a constant:

const ErrCodeNotFound = 1

And an error:

type ErrNotFound barrister.CustomJsonRpcError

And the automapping code needed (err code <=> err type) so I could return the *mypkg.ErrNotFound from my service implementation and it would be returned as *mypkg.ErrNotFound on my client side.

Of course this is cross-platform, in case of Java or PHP, for example, a NotFoundException would be thrown, etc.

This could be gradually introduced in the languages, as languages with lack of this support could use the error codes included in the IDL just like documentation and base their implementation on those codes.

To separate concerns I'd like to include struct definitions from other idl files.

Is this feature in the scope?

Example:

• event.idl

struct Event {
   name string
}

• chat.idl

include 'event.idl'

struct Message extends Event {
   msg string
}