protostar 0.1.0.beta1

data/lib/protostar/compiler/emitters.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+module Protostar
+  class Compiler
+    # Code generators. Each takes built {Schema::File}s and returns a Hash of
+    # output path to contents.
+    module Emitters
+      # Raised when a file cannot be emitted, with protoc's generator message
+      class Error < Protostar::Error; end
+
+      # The files whose generated Ruby ships with protostar under
+      # `protostar/google/protobuf/`, with constants under
+      # `Protostar::Google::Protobuf`
+      BOOTSTRAP = %w[
+        google/protobuf/descriptor.proto google/protobuf/compiler/plugin.proto google/protobuf/any.proto
+        google/protobuf/api.proto google/protobuf/duration.proto google/protobuf/empty.proto
+        google/protobuf/field_mask.proto google/protobuf/source_context.proto google/protobuf/struct.proto
+        google/protobuf/timestamp.proto google/protobuf/type.proto google/protobuf/wrappers.proto
+      ].freeze
+
+      # The Ruby module the bootstrap's `google.protobuf` package lives in
+      BOOTSTRAP_NAMESPACE = "Protostar::Google::Protobuf"
+
+      autoload :Ruby, ::File.expand_path("emitters/ruby", __dir__)
+      autoload :DescriptorSet, ::File.expand_path("emitters/descriptor_set", __dir__)
+      autoload :GoogleRuby, ::File.expand_path("emitters/google_ruby", __dir__)
+      autoload :Rbs, ::File.expand_path("emitters/rbs", __dir__)
+      autoload :ProtostarRbs, ::File.expand_path("emitters/protostar_rbs", __dir__)
+      autoload :Grpc, ::File.expand_path("emitters/grpc", __dir__)
+
+      # protoc's Ruby generator naming rules (ruby_generator.cc), which grpc
+      # stubs and application code depend on
+      module Naming
+        # Characters protoc refuses in `ruby_package`
+        BANNED_RUBY_PACKAGE = ";`{}()'\"$#=<>|&[]/\\@%\n\r!?*~^,\0"
+
+        module_function
+
+        # "foo/bar.proto" to "foo/bar_pb"
+        def require_name(proto_file)
+          dot = proto_file.rindex(".")
+          "#{dot ? proto_file[0, dot] : proto_file}_pb"
+        end
+
+        # snake_case package part to a module name: "foo_bar" to "FooBar"
+        def package_to_module(name)
+          out = +""
+          upper = true
+          name.each_char do |c|
+            if c == "_"
+              upper = true
+            else
+              out << (upper ? upcase(c) : c)
+              upper = false
+            end
+          end
+          out
+        end
+
+        # A message or enum name as a Ruby constant: first letter
+        # capitalised, "PB_" prefixed when it does not start with a letter
+        def rubify_constant(name)
+          return name if name.empty?
+          first = name[0]
+          if first.between?("a", "z")
+            upcase(first) + name[1..]
+          elsif !first.between?("A", "Z")
+            "PB_#{name}"
+          else
+            name
+          end
+        end
+
+        # The modules a file's constants live in, outermost first: protoc's
+        # GeneratePackageModules
+        # @param file [Schema::File]
+        # @param namespace [String, nil] overrides the package and `ruby_package`
+        # @return [Array<String>]
+        def module_path(file, namespace = nil)
+          return namespace.split("::") if namespace
+          convert = true
+          if (package = file.options.ruby_package)
+            convert = false if package.include?("::")
+          else
+            package = file.package
+          end
+          delimiter = convert ? "." : "::"
+          parts = []
+          until package.empty?
+            at = package.index(delimiter)
+            if at
+              parts << package[0, at]
+              package = package[(at + delimiter.size)..]
+            else
+              parts << package
+              package = ""
+            end
+          end
+          convert ? parts.map { |p| package_to_module(p) } : parts
+        end
+
+        # protoc's check on `ruby_package`
+        # @raise [Emitters::Error]
+        def check_ruby_package(file)
+          file.options.ruby_package&.each_char do |c|
+            next unless BANNED_RUBY_PACKAGE.include?(c)
+            raise Emitters::Error, "Invalid character in ruby_package option: character '#{c}' is not allowed " \
+              "because it could enable code injection."
+          end
+        end
+
+        # The constant path of a message or enum relative to its file's module
+        # @param descriptor [Schema::Message, Schema::Enum]
+        def relative_constant(descriptor)
+          names = []
+          d = descriptor
+          while d
+            names.unshift(rubify_constant(d.name))
+            d = d.containing_message
+          end
+          names.join("::")
+        end
+
+        def upcase(c)
+          c.between?("a", "z") ? c.upcase : c
+        end
+      end
+
+      # protoc's io::Printer: text is indented at the start of every line
+      # that is not empty
+      class Printer
+        def initialize
+          @out = +""
+          @indent = ""
+          @at_start = true
+        end
+
+        def print(text)
+          text.each_char do |c|
+            if c == "\n"
+              @at_start = true
+            elsif @at_start
+              @out << @indent
+              @at_start = false
+            end
+            @out << c
+          end
+          self
+        end
+
+        def indent
+          @indent += "  "
+        end
+
+        def outdent
+          @indent = @indent[0...-2]
+        end
+
+        def to_s
+          @out
+        end
+      end
+
+      # Ruby source for literal values: Strings as UTF-8 text or binary with
+      # `.b`, floats exactly, Hashes and Arrays broken over lines when long
+      module Literal
+        WIDTH = 100
+        ESCAPES = {"\n" => "\\n", "\t" => "\\t", "\r" => "\\r", "\"" => "\\\"", "\\" => "\\\\", "\e" => "\\e",
+                   "\a" => "\\a", "\b" => "\\b", "\f" => "\\f", "\v" => "\\v"}.freeze
+
+        module_function
+
+        # @param value [Object]
+        # @param indent [Integer] the indentation of the line the literal is on
+        # @param start [Integer] the column the literal starts on
+        # @return [String] on one line when it fits, otherwise one element per line
+        def call(value, indent = 0, start = indent)
+          flat = flat(value)
+          return flat if start + flat.size <= WIDTH || !(value.is_a?(Hash) || value.is_a?(Array)) || value.empty?
+          pad = " " * (indent + 2)
+          items = if value.is_a?(Array)
+            value.map { |v| pad + call(v, indent + 2) }
+          else
+            value.map { |k, v| pad + key(k) + call(v, indent + 2, indent + 2 + key(k).size) }
+          end
+          open, close = value.is_a?(Array) ? ["[", "]"] : ["{", "}"]
+          "#{open}\n#{items.join(",\n")}\n#{" " * indent}#{close}"
+        end
+
+        def flat(value)
+          case value
+          when Hash then value.empty? ? "{}" : "{#{value.map { |k, v| key(k) + flat(v) }.join(", ")}}"
+          when Array then "[#{value.map { |v| flat(v) }.join(", ")}]"
+          when String then string(value)
+          when Symbol then value.inspect
+          when Float then float(value)
+          when Integer, true, false, nil then value.inspect
+          when Range then "#{value.begin}..#{value.end}"
+          else raise ArgumentError, "no literal for #{value.class}"
+          end
+        end
+
+        def key(k)
+          if k.is_a?(Symbol) && /\A[A-Za-z_][A-Za-z0-9_]*\z/.match?(k)
+            "#{k}: "
+          else
+            "#{flat(k)} => "
+          end
+        end
+
+        def float(value)
+          return "Float::NAN" if value.nan?
+          return (value > 0) ? "Float::INFINITY" : "-Float::INFINITY" if value.infinite?
+          value.inspect
+        end
+
+        # A double-quoted literal; binary Strings, and Strings that are not
+        # valid UTF-8, are escaped byte by byte and marked `.b`
+        def string(value)
+          binary = value.encoding == Encoding::BINARY || !value.dup.force_encoding(Encoding::UTF_8).valid_encoding?
+          out = +"\""
+          if binary
+            value.each_byte { |b| out << byte(b) }
+            out << "\".b"
+          else
+            text = (value.encoding == Encoding::UTF_8) ? value : value.dup.force_encoding(Encoding::UTF_8)
+            text.each_char { |c| out << char(c) }
+            out << "\""
+          end
+          out
+        end
+
+        def byte(b)
+          c = b.chr
+          if (escaped = ESCAPES[c])
+            escaped
+          elsif b < 0x20 || b >= 0x7F
+            format("\\x%02X", b)
+          elsif c == "#"
+            "\\#"
+          else
+            c
+          end
+        end
+
+        def char(c)
+          if (escaped = ESCAPES[c])
+            escaped
+          elsif c == "#"
+            "\\#"
+          elsif c.ord < 0x20 || c.ord == 0x7F
+            format("\\x%02X", c.ord)
+          elsif c.ord >= 0x80 && !printable?(c)
+            format("\\u{%X}", c.ord)
+          else
+            c
+          end
+        end
+
+        # Formatting and line-breaking code points are escaped so that a
+        # generated line never breaks or reorders visually
+        def printable?(c)
+          !/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}\p{Cs}\p{Co}\p{Cn}]/.match?(c)
+        end
+      end
+    end
+  end
+end

data/lib/protostar/compiler/include/LICENSE

@@ -0,0 +1,32 @@
+Copyright 2008 Google Inc.  All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+    * Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the following disclaimer
+in the documentation and/or other materials provided with the
+distribution.
+    * Neither the name of Google Inc. nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+Code generated by the Protocol Buffer compiler is owned by the owner
+of the input file used when generating it.  This code is not
+standalone and requires a support library to be linked with it.  This
+support library is itself covered by the above license.

data/lib/protostar/compiler/include/google/protobuf/any.proto

@@ -0,0 +1,106 @@
+// Protocol Buffers - Google's data interchange format
+// Copyright 2008 Google Inc.  All rights reserved.
+// https://developers.google.com/protocol-buffers/
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are
+// met:
+//
+//     * Redistributions of source code must retain the above copyright
+// notice, this list of conditions and the following disclaimer.
+//     * Redistributions in binary form must reproduce the above
+// copyright notice, this list of conditions and the following disclaimer
+// in the documentation and/or other materials provided with the
+// distribution.
+//     * Neither the name of Google Inc. nor the names of its
+// contributors may be used to endorse or promote products derived from
+// this software without specific prior written permission.
+//
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+syntax = "proto3";
+
+package google.protobuf;
+
+option go_package = "google.golang.org/protobuf/types/known/anypb";
+option java_package = "com.google.protobuf";
+option java_outer_classname = "AnyProto";
+option java_multiple_files = true;
+option objc_class_prefix = "GPB";
+option csharp_namespace = "Google.Protobuf.WellKnownTypes";
+
+// `Any` contains an arbitrary serialized protocol buffer message along with a
+// URL that describes the type of the serialized message.
+//
+// In its binary encoding, an `Any` is an ordinary message; but in other wire
+// forms like JSON, it has a special encoding. The format of the type URL is
+// described on the `type_url` field.
+//
+// Protobuf APIs provide utilities to interact with `Any` values:
+//
+// - A 'pack' operation accepts a message and constructs a generic `Any` wrapper
+//   around it.
+// - An 'unpack' operation reads the content of an `Any` message, either into an
+//   existing message or a new one. Unpack operations must check the type of the
+//   value they unpack against the declared `type_url`.
+// - An 'is' operation decides whether an `Any` contains a message of the given
+//   type, i.e. whether it can 'unpack' that type.
+//
+// The JSON format representation of an `Any` follows one of these cases:
+//
+// - For types without special-cased JSON encodings, the JSON format
+//   representation of the `Any` is the same as that of the message, with an
+//   additional `@type` field which contains the type URL.
+// - For types with special-cased JSON encodings (typically called 'well-known'
+//   types, listed in https://protobuf.dev/programming-guides/json/#any), the
+//   JSON format representation has a key `@type` which contains the type URL
+//   and a key `value` which contains the JSON-serialized value.
+//
+// The text format representation of an `Any` is like a message with one field
+// whose name is the type URL in brackets. For example, an `Any` containing a
+// `foo.Bar` message may be written `[type.googleapis.com/foo.Bar] { a: 2 }`.
+message Any {
+  // Identifies the type of the serialized Protobuf message with a URI reference
+  // consisting of a prefix ending in a slash and the fully-qualified type name.
+  //
+  // Example: type.googleapis.com/google.protobuf.StringValue
+  //
+  // This string must contain at least one `/` character, and the content after
+  // the last `/` must be the fully-qualified name of the type in canonical
+  // form, without a leading dot. Do not write a scheme on these URI references
+  // so that clients do not attempt to contact them.
+  //
+  // The prefix is arbitrary and Protobuf implementations are expected to
+  // simply strip off everything up to and including the last `/` to identify
+  // the type. `type.googleapis.com/` is a common default prefix that some
+  // legacy implementations require. This prefix does not indicate the origin of
+  // the type, and URIs containing it are not expected to respond to any
+  // requests.
+  //
+  // All type URL strings must be legal URI references with the additional
+  // restriction (for the text format) that the content of the reference
+  // must consist only of alphanumeric characters, percent-encoded escapes, and
+  // characters in the following set (not including the outer backticks):
+  // `/-.~_!$&()*+,;=`. Despite our allowing percent encodings, implementations
+  // should not unescape them to prevent confusion with existing parsers. For
+  // example, `type.googleapis.com%2FFoo` should be rejected.
+  //
+  // In the original design of `Any`, the possibility of launching a type
+  // resolution service at these type URLs was considered but Protobuf never
+  // implemented one and considers contacting these URLs to be problematic and
+  // a potential security issue. Do not attempt to contact type URLs.
+  string type_url = 1;
+
+  // Holds a Protobuf serialization of the type described by type_url.
+  bytes value = 2;
+}

data/lib/protostar/compiler/include/google/protobuf/api.proto

@@ -0,0 +1,229 @@
+// Protocol Buffers - Google's data interchange format
+// Copyright 2008 Google Inc.  All rights reserved.
+// https://developers.google.com/protocol-buffers/
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are
+// met:
+//
+//     * Redistributions of source code must retain the above copyright
+// notice, this list of conditions and the following disclaimer.
+//     * Redistributions in binary form must reproduce the above
+// copyright notice, this list of conditions and the following disclaimer
+// in the documentation and/or other materials provided with the
+// distribution.
+//     * Neither the name of Google Inc. nor the names of its
+// contributors may be used to endorse or promote products derived from
+// this software without specific prior written permission.
+//
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+syntax = "proto3";
+
+package google.protobuf;
+
+import "google/protobuf/source_context.proto";
+import "google/protobuf/type.proto";
+
+option java_package = "com.google.protobuf";
+option java_outer_classname = "ApiProto";
+option java_multiple_files = true;
+option objc_class_prefix = "GPB";
+option csharp_namespace = "Google.Protobuf.WellKnownTypes";
+option go_package = "google.golang.org/protobuf/types/known/apipb";
+
+// Api is a light-weight descriptor for an API Interface.
+//
+// Interfaces are also described as "protocol buffer services" in some contexts,
+// such as by the "service" keyword in a .proto file, but they are different
+// from API Services, which represent a concrete implementation of an interface
+// as opposed to simply a description of methods and bindings. They are also
+// sometimes simply referred to as "APIs" in other contexts, such as the name of
+// this message itself. See https://cloud.google.com/apis/design/glossary for
+// detailed terminology.
+//
+// New usages of this message as an alternative to ServiceDescriptorProto are
+// strongly discouraged. This message does not reliability preserve all
+// information necessary to model the schema and preserve semantics. Instead
+// make use of FileDescriptorSet which preserves the necessary information.
+message Api {
+  // The fully qualified name of this interface, including package name
+  // followed by the interface's simple name.
+  string name = 1;
+
+  // The methods of this interface, in unspecified order.
+  repeated Method methods = 2;
+
+  // Any metadata attached to the interface.
+  repeated Option options = 3;
+
+  // A version string for this interface. If specified, must have the form
+  // `major-version.minor-version`, as in `1.10`. If the minor version is
+  // omitted, it defaults to zero. If the entire version field is empty, the
+  // major version is derived from the package name, as outlined below. If the
+  // field is not empty, the version in the package name will be verified to be
+  // consistent with what is provided here.
+  //
+  // The versioning schema uses [semantic
+  // versioning](http://semver.org) where the major version number
+  // indicates a breaking change and the minor version an additive,
+  // non-breaking change. Both version numbers are signals to users
+  // what to expect from different versions, and should be carefully
+  // chosen based on the product plan.
+  //
+  // The major version is also reflected in the package name of the
+  // interface, which must end in `v<major-version>`, as in
+  // `google.feature.v1`. For major versions 0 and 1, the suffix can
+  // be omitted. Zero major versions must only be used for
+  // experimental, non-GA interfaces.
+  //
+  string version = 4;
+
+  // Source context for the protocol buffer service represented by this
+  // message.
+  SourceContext source_context = 5;
+
+  // Included interfaces. See [Mixin][].
+  repeated Mixin mixins = 6;
+
+  // The source syntax of the service.
+  Syntax syntax = 7;
+
+  // The source edition string, only valid when syntax is SYNTAX_EDITIONS.
+  string edition = 8;
+}
+
+// Method represents a method of an API interface.
+//
+// New usages of this message as an alternative to MethodDescriptorProto are
+// strongly discouraged. This message does not reliability preserve all
+// information necessary to model the schema and preserve semantics. Instead
+// make use of FileDescriptorSet which preserves the necessary information.
+message Method {
+  // The simple name of this method.
+  string name = 1;
+
+  // A URL of the input message type.
+  string request_type_url = 2;
+
+  // If true, the request is streamed.
+  bool request_streaming = 3;
+
+  // The URL of the output message type.
+  string response_type_url = 4;
+
+  // If true, the response is streamed.
+  bool response_streaming = 5;
+
+  // Any metadata attached to the method.
+  repeated Option options = 6;
+
+  // The source syntax of this method.
+  //
+  // This field should be ignored, instead the syntax should be inherited from
+  // Api. This is similar to Field and EnumValue.
+  Syntax syntax = 7 [deprecated = true];
+
+  // The source edition string, only valid when syntax is SYNTAX_EDITIONS.
+  //
+  // This field should be ignored, instead the edition should be inherited from
+  // Api. This is similar to Field and EnumValue.
+  string edition = 8 [deprecated = true];
+}
+
+// Declares an API Interface to be included in this interface. The including
+// interface must redeclare all the methods from the included interface, but
+// documentation and options are inherited as follows:
+//
+// - If after comment and whitespace stripping, the documentation
+//   string of the redeclared method is empty, it will be inherited
+//   from the original method.
+//
+// - Each annotation belonging to the service config (http,
+//   visibility) which is not set in the redeclared method will be
+//   inherited.
+//
+// - If an http annotation is inherited, the path pattern will be
+//   modified as follows. Any version prefix will be replaced by the
+//   version of the including interface plus the [root][] path if
+//   specified.
+//
+// Example of a simple mixin:
+//
+//     package google.acl.v1;
+//     service AccessControl {
+//       // Get the underlying ACL object.
+//       rpc GetAcl(GetAclRequest) returns (Acl) {
+//         option (google.api.http).get = "/v1/{resource=**}:getAcl";
+//       }
+//     }
+//
+//     package google.storage.v2;
+//     service Storage {
+//       rpc GetAcl(GetAclRequest) returns (Acl);
+//
+//       // Get a data record.
+//       rpc GetData(GetDataRequest) returns (Data) {
+//         option (google.api.http).get = "/v2/{resource=**}";
+//       }
+//     }
+//
+// Example of a mixin configuration:
+//
+//     apis:
+//     - name: google.storage.v2.Storage
+//       mixins:
+//       - name: google.acl.v1.AccessControl
+//
+// The mixin construct implies that all methods in `AccessControl` are
+// also declared with same name and request/response types in
+// `Storage`. A documentation generator or annotation processor will
+// see the effective `Storage.GetAcl` method after inheriting
+// documentation and annotations as follows:
+//
+//     service Storage {
+//       // Get the underlying ACL object.
+//       rpc GetAcl(GetAclRequest) returns (Acl) {
+//         option (google.api.http).get = "/v2/{resource=**}:getAcl";
+//       }
+//       ...
+//     }
+//
+// Note how the version in the path pattern changed from `v1` to `v2`.
+//
+// If the `root` field in the mixin is specified, it should be a
+// relative path under which inherited HTTP paths are placed. Example:
+//
+//     apis:
+//     - name: google.storage.v2.Storage
+//       mixins:
+//       - name: google.acl.v1.AccessControl
+//         root: acls
+//
+// This implies the following inherited HTTP annotation:
+//
+//     service Storage {
+//       // Get the underlying ACL object.
+//       rpc GetAcl(GetAclRequest) returns (Acl) {
+//         option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";
+//       }
+//       ...
+//     }
+message Mixin {
+  // The fully qualified name of the interface which is included.
+  string name = 1;
+
+  // If non-empty specifies a path under which inherited HTTP paths
+  // are rooted.
+  string root = 2;
+}