Schema for Juju RPC messages

[John A Meinel]

We've had some requests from people trying to drive Juju that it would
actually be really nice if we were stricter with the messages that we
accept on our API. Specifically, as we've changed the API methods, they had
several hard-to-debug problems because they were passing a parameter that
was named incorrectly, and Juju was not giving them any indication that
something was wrong.

I put together a (very hackish) test branch, to see if I could use
JSONSchema to define our request and response messages, and give nicer
error messages (rather than silent acceptance). As I was working with JSON,
I realized the extra " and { characters really got in the way of making a
document that was readable, so I leveraged our existing YAML to JSON
conversion mechanisms to write the description in YAML and then load the
object tree into JSONSchema to validate our requests.

I did end up getting basic validation of the outer structure (just the
Request/Response message, not the contents of Parameters) functioning here:

https://github.com/jameinel/juju/blob/yaml-schema-rpc/rpc/jsoncodec/codec.go
You can see what some of the error messages look like here:

https://github.com/jameinel/juju/blob/yaml-schema-rpc/rpc/jsoncodec/codec_test.go

The actual code itself isn't useful as is, because it needs to have the
schema validation stuff pulled out into its own file, etc. But it does give
a proof-of-concept of basic message validation. I'm not super excited by
some of the error messages (gojsonschema.ResultError.Description is very
nice by itself for missing keys, extra properties, etc, but not enough
information for invalid values, while ResultError.String() is overly
verbose in the opposite way.)

I'd like to get a bit of feedback on whether people would find this
interesting, especially if we brought that all the way into the Param
structs as well. I haven't done any benchmarking to determine if this is a
large overhead or not. But the golfing community seems determined to not do
a Strict Unmarshal function, and seems to be recommending using a Schema
instead.

I'm not completely sold either way, though I do find the YAML format for
the schema description to be far more human readable than the JSON format.

Thoughts?

John
=:->
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/juju-dev/attachments/20160727/800da978/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: message-schema.json
Type: application/json
Size: 2702 bytes
Desc: not available
URL: <https://lists.ubuntu.com/archives/juju-dev/attachments/20160727/800da978/attachment.json>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: message-schema.yaml
Type: application/octet-stream
Size: 2551 bytes
Desc: not available
URL: <https://lists.ubuntu.com/archives/juju-dev/attachments/20160727/800da978/attachment.obj>