Add support for explicit protocol versioning (#39)

This doesn't add actual version negotiation, because it's expected
that embedded hots will tightly control which compiler versions they
install.

Partially addresses #37
Closes #14

CHANGELOG.md

@@ -0,0 +1,7 @@
+## 1.0.0-beta.6
+
+* Added protocol versions and created this changelog.
+
+* Added the `VersionRequest` and `VersionResponse` messages.
+
+* Delimit messages with varints rather than fixed-size integers.

README.md

@@ -1,4 +1,4 @@
-## The Embedded Sass Protocol
+## The Embedded Sass Protocol (pending 1.0.0-beta.6)
 
 * [Overview](#overview)
 * [RPCs](#rpcs)
@@ -13,6 +13,7 @@
   * [Booleans](#booleans)
   * [Null](#null)
   * [Functions](#functions)
+* [Versioning](#versioning)
 
 This repository defines a bidirectional protocol for communicating between a
 Sass implementation and a host environment. It allows the host environment to
@@ -286,3 +287,24 @@ functions' signatures.
 
 Two first-class functions are equal if they have the same ID and they're either
 both `CompilerFunction`s or both `HostFunction`s.
+
+### Versioning
+
+This protocol is versioned according to [semver 2.0.0]. Compatibility is
+considered from the perspective of the host. For example, if a new
+`InboundMessage` type is added, that's considered a "backwards compatible"
+change because older hosts can simply opt not to use it, even though from the
+perspective of the compiler a new message type would be a breaking change.
+
+Hosts are generally expected to be responsible for installing appropriate
+compiler versions as part of their installation process, which should limit the
+potential for incompatible versions between the two. For this reason, version
+numbers are intended to be primarily an advisory for humans as to the degree of
+change over time.
+
+In some cases, the version number will be marked as "pending". This indicates
+that the next version of the protocol is still under active development, and may
+be waiting for additional pull requests before it's finalized. Hosts and
+compilers should never cut releases that target pending protocol versions.
+
+[semver 2.0.0]: https://semver.org/spec/v2.0.0.html

embedded_sass.proto

@@ -10,6 +10,16 @@ package sass.embedded_protocol;
 // provides a `oneof` that makes it possible to determine the type of each
 // inbound message.
 message InboundMessage {
+  // A request for information about the version of the embedded compiler. The
+  // host can use this to provide diagnostic information to the user, to check
+  // which features the compiler supports, or to ensure that it's compatible
+  // with the same protocol version the compiler supports.
+  message VersionRequest {
+    // This message's contents are intentionally empty. It just acts as a signal
+    // to the compiler to send a VersionResponse. More fields may be added in
+    // the future.
+  }
+
   // A request that compiles an entrypoint to CSS.
   message CompileRequest {
     // This compilation's request id. This is included in messages sent from the
@@ -231,13 +241,32 @@ message InboundMessage {
     ImportResponse importResponse = 4;
     FileImportResponse fileImportResponse = 5;
     FunctionCallResponse functionCallResponse = 6;
+    VersionRequest versionRequest = 7;
   }
 }
 
 // The wrapper type for all messages sent from the compiler to the host. This
 // provides a `oneof` that makes it possible to determine the type of each
 // outbound message.
 message OutboundMessage {
+  // A response that contains the version of the embedded compiler.
+  message VersionResponse {
+    // The version of the embedded protocol, in semver format.
+    string protocol_version = 1;
+
+    // The version of the embedded compiler package. This has no guaranteed
+    // format, although compilers are encouraged to use semver.
+    string compiler_version = 2;
+
+    // The version of the Sass implementation that the embedded compiler wraps.
+    // This has no guaranteed format, although Sass implementations are
+    // encouraged to use semver.
+    string implementation_version = 3;
+
+    // The name of the Sass implementation that the embedded compiler wraps.
+    string implementation_name = 4;
+  }
+
   // A response that contains the result of a compilation.
   message CompileResponse {
     // The compilation's request id. Mandatory.
@@ -475,6 +504,7 @@ message OutboundMessage {
     ImportRequest importRequest = 5;
     FileImportRequest fileImportRequest = 6;
     FunctionCallRequest functionCallRequest = 7;
+    VersionResponse versionResponse = 8;
   }
 }