Spec questions

[technoweenie]

I spent some time this weekend building a Golang implementation: https://github.com/github/go-chatops. The spec is really good, but I ran into a few questions:

1. What is the difference between a method name (options in the protocol doc example) and the path (wcid)? In that example, is it possible to leave out the path property if it happened to be options?
2. Why does a chat command POST have the method path in the URL and the input JSON? Does it matter if they conflict?
3. What is the keyid in a signature header like Chatops-Signature: Signature keyid="rsakey1",signature="<base64-encoded-signature>"? Will it be something like keyid="hubot" in our environment? Doesn't look like it's needed to sign or verify CRPC commands, but is it worth logging?
4. What about HTTP response codes? You can see the HTTP statuses returned in this file. Is that legit, or should I return 200, potentially with json rpc error messages to denote a CRPC protocol error?

[bhuga]

What is the difference between a method name (options in the protocol doc example) and the path (wcid)? In that example, is it possible to leave out the path property if it happened to be options?

The method name is what will be passed in as the method name, and the path is where it will be passed. You could have no path and respond to POST and GET differently at the same location, executing and listing, respectively. This is designed so that servers can be flexible. Rails, for example, wants a path-per-action.

Why does a chat command POST have the method path in the URL and the input JSON? Does it matter if they conflict?

No, it doesn't matter. Again, this is just so that servers can specify path/routing information as it makes sense to them. You could just have POST /_chatops and the server should pivot off of the given method.

What is the keyid in a signature header like Chatops-Signature: Signature keyid="rsakey1",signature=""? Will it be something like keyid="hubot" in our environment? Doesn't look like it's needed to sign or verify CRPC commands, but is it worth logging?

Think of it like a user-agent header. This lets servers respond differently to differently named keys, if desired, or can be used in token rolling or whatever else. We're not using it internally for anything yet, but imagine having slack and bastion as two options.

What about HTTP response codes? You can see the HTTP statuses returned in this file. Is that legit, or should I return 200, potentially with json rpc error messages to denote a CRPC protocol error?

When we did the shell adapter, we found it was handy to pivot off of response codes to set exit status. But if you don't care about that, it's fine to return error messages with a 200. The shared rails controller made it easy to implement these for everything, so we went ahead and did it. It might not be worth it for you.

[technoweenie]

Thanks for the responses! 1 follow up question:

Let's say my chatops list looks like this:

{
 "namespace": "deploy",
 "help": null,
 "version": 3,
 "error_response": "The server had an unexpected error. More information is perhaps available in the [error tracker](https://example.com)"
 "methods": {
   "options": {
     "help": "hubot deploy options <app> - List available environments for <app>",
     "regex": "options(?: (?<app>\\S+))?",
     "params": [
       "app"
     ],
     "path": ""
   }
 }
}

What does hubot's request look like?

A) No path, empty method in the request

POST /_chatops HTTP/1.1
Accept: application/json
Content-type: application/json
Content-length: 77

{"user":"bhuga","method":"","params":{"app": "hubot"},"room_id":"developer-experience"}

B) No path, method in the request equals the methods hash key. If this, it makes me feel like the example for POST /_chatops/wcid should be sending "method":"options".

POST /_chatops HTTP/1.1
Accept: application/json
Content-type: application/json
Content-length: 77

{"user":"bhuga","method":"options","params":{"app": "hubot"},"room_id":"developer-experience"}

[bhuga]

Sorry, I see the confusion now. The key for each method in the listing will be used as the method field. Option B will happen.

[technoweenie]

Sweet. Filed a PR to fix that up in the docs. My take aways from this in github/go-chatops:

1. Not doing any magical method path based on the name.
2. Will send the keyid to splunk/haystack.
3. Will continue sending non-200 response codes, but as jsonrpc error objects instead (matching the rails implementation