api/socket: Add JSON Schema and Go types for the command-line API socket messages

Even though there aren't many new types, these are fairly different
from the rest of the runtime-tools code, and a separate package lets
folks pull in only the code they need (assuming they are sophisticated
enough to grab only a subset of the Git repository).

Mrunal approved the JSON Schema landing under schema/ [1].

[1]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2017/opencontainers.2017-03-15-21.02.log.html#l-122

Signed-off-by: W. Trevor King <wking@tremily.us>

Author: wking

api/socket/socket.go

@@ -0,0 +1,23 @@
+package socket
+
+// Message is the normal data for messages passed on the console socket.
+type Message struct {
+	// Type of message being passed
+	Type string `json:"type"`
+}
+
+// TerminalRequest is the normal data for messages passing a pseudoterminal master.
+type TerminalRequest struct {
+	Message
+
+	// Container ID for the container whose pseudoterminal master is being set.
+	Container string `json:"container"`
+}
+
+// Response is the normal data for response messages.
+type Response struct {
+	Message
+
+	// Message is a phrase describing the response.
+	Message string `json:"message,omitempty"`
+}

docs/command-line-interface.md

@@ -85,7 +85,7 @@ The socket type MUST be [`SOCK_SEQPACKET`][socket-types] or [`SOCK_STREAM`][sock
 The server MUST send a single response for each runtime request.
 The [normal data][socket-queue] ([`msghdr.msg_iov*`][socket.h]) of all messages MUST be [UTF-8][] [JSON](glossary.md#json).
 
-There are [JSON Schemas](schema/README.md) and [Go bindings](specs-go/socket/socket.go) for the messages specified in this section.
+There are [JSON Schemas](../schema/README.md#oci-runtime-command-line-interface) and [Go bindings](../api/socket/socket.go) for the messages specified in this section.
 
 ##### Requests
 

schema/README.md

@@ -0,0 +1,14 @@
+# JSON schema
+
+This directory contains [JSON Schema][json-schema] for validating JSON covered by local specifications.
+The runtime specification includes [a generic command line tool][validate] which may be used to validate JSON with these schemas.
+
+## OCI Runtime Command Line Interface
+
+The [Runtime Command Line Interface](../docs/command-line-interface.md) defines:
+
+* [Terminal requests](../docs/command-line-interface.md#requests), which may be validated against [`socket-terminal-request.json`](socket-terminal-request.json).
+* [Responses](../docs/command-line-interface.md#reqponses), which may be validated against [`socket-response.json`](socket-response.json).
+
+[json-schema]: http://json-schema.org/
+[validate]: https://github.com/opencontainers/runtime-spec/tree/v1.0.0-rc5/schema#utility

schema/socket-response.json

@@ -0,0 +1,24 @@
+{
+  "description": "Open Container Runtime Socket Response Schema",
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "id": "https://opencontainers.org/schema/runtime/socket/response",
+  "type": "object",
+  "properties": {
+    "type": {
+      "id": "https://opencontainers.org/schema/runtime/socket/response/type",
+      "type": "string",
+      "enum": [
+        "success",
+        "error"
+      ]
+    },
+    "message": {
+      "id": "https://opencontainers.org/schema/runtime/socket/response/message",
+      "description": "A phrase describing the response.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "type"
+  ]
+}

schema/socket-terminal-request.json

@@ -0,0 +1,24 @@
+{
+  "description": "Open Container Runtime Socket Teminal Request Schema",
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "id": "https://opencontainers.org/schema/runtime/socket/terminal-request",
+  "type": "object",
+  "properties": {
+    "type": {
+      "id": "https://opencontainers.org/schema/runtime/socket/terminal/request/type",
+      "type": "string",
+      "enum": [
+        "terminal"
+      ]
+    },
+    "container": {
+      "id": "https://opencontainers.org/schema/runtime/state/id",
+      "description": "the container's ID",
+      "type": "string"
+    }
+  },
+  "required": [
+    "type",
+    "container"
+  ]
+}