Add documentation for [SubService]

Author: mgravell

docs/gettingstarted.md

@@ -74,9 +74,63 @@ public class MultiplyResult
 Object models can be arbitrarily deep and complex (including lists, arrays, etc), but should be trees (not graphs).
 
 
-Service contracts are interfaces marked with `[ServiceContract]`. You can optionally specify the gRPC service name, otherwise it'll use
-reasonable convention-based defaults. Individual RPC calls are methods, which can optionally be marked with `[OperationContract]` to control
-the name.
+Service contracts are interfaces marked with `[ServiceContract]` (from `System.ServiceModel`) or `[Service]` (protobuf-net.Grpc inbuilt). You can optionally specify the gRPC service name, otherwise it'll use
+reasonable convention-based defaults. Individual RPC calls are methods, which can optionally be marked with `[OperationContract]` (from `System.ServiceModel`) or `[Operation]` (protobuf-net.Grpc inbuilt) to control
+the name. There is also `[SubService]`, which is used as below.
+
+### Interface inheritance works, with 2 possible scenarios:
+
+1. Inherited interfaces as distinct routable services
+
+Consider:
+
+``` c#
+[Service("foo")]
+interface IFoo : IBar
+{
+    Task A();
+}
+[Service("bar")]
+interface IBar
+{
+    Task B();
+}
+```
+
+Here, the bindings are `/foo/A` and `/bar/B`. A client can be constructed for `IBar` by itself, since `IBar` is routable (via `/bar/`). If there was an additional service that *also* inherited `IBar`, they
+could not be used independently, since both uses would want to route via `/bar/.
+
+2. Inherited interfaces as composition
+
+Consider:
+
+``` c#
+[Service("foo")]
+interface IFoo : IBar
+{
+    Task A();
+}
+[SubService]
+interface IBar
+{
+    Task B();
+}
+```
+
+Here, the bindings are `/foo/A`, `/foo/B`. The methods from `IBar` are lifted upwards and form part of the `IFoo` service. As a consequence, a client **cannot** be constructed for `IBar` in isolation, as
+`IBar` is not routable without knowing the top-level service to use. The upside of this, however, is that we can add additional services with the same common API, and route them independently. For example, we can add:
+
+``` c#
+[Service("blap")]
+interface IBlap : IBar
+{
+    Task C();
+}
+```
+
+This adds the bindings `/blap/C` and `/blap/B`, so now we have two completely independent routable implementations of `B()`. This is especially useful for generic scenarios, common repositories, etc.
+
+### Call types
 
 In gRPC, there are 4 types of call available:
 
@@ -88,7 +142,7 @@ In gRPC, there are 4 types of call available:
 Let's start with unary; a simple example there might be:
 
 ``` c#
-[ServiceContract(Name = "Hyper.Calculator")]
+[ServiceContract(Name = "Hyper.Calculator")] // or [Service("Hyper.Calculator")]
 public interface ICalculator
 {
     ValueTask<MultiplyResult> MultiplyAsync(MultiplyRequest request);

tests/protobuf-net.Grpc.Test/ContractOperationTests.cs

@@ -64,15 +64,15 @@ public void ServerSignatureCount()
         [Fact]
         public void CheckAllMethodsCovered()
         {
-            var expected =  new HashSet<string>(typeof(IAllOptions).GetMethods(BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic).Select(x => x.Name));
+            var expected = new HashSet<string>(typeof(IAllOptions).GetMethods(BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic).Select(x => x.Name));
             Assert.Equal(ContractOperation.SignatureCount, expected.Count);
 
             var attribs = GetType().GetMethod(nameof(CheckMethodIdentification))!.GetCustomAttributesData();
-            foreach(var attrib in attribs)
+            foreach (var attrib in attribs)
             {
                 if (attrib.AttributeType != typeof(InlineDataAttribute)) continue;
 
-                foreach(var arg in attrib.ConstructorArguments)
+                foreach (var arg in attrib.ConstructorArguments)
                 {
                     var vals = (ReadOnlyCollection<CustomAttributeTypedArgument>)arg.Value!;
                     var name = (string)vals[0].Value!;
@@ -82,45 +82,77 @@ public void CheckAllMethodsCovered()
 
             Assert.Empty(expected);
         }
-        
-        
+
+
         [Service]
         [SubService]
         public interface IIServiceWithBothServiceAndSubServiceAttributes
         {
             void SomeMethod();
         }
-    
+
         [Fact]
         public void WhenInterfaceHasAttributesServiceAndSubService_Throw()
         {
             var config = BinderConfiguration.Default;
             Action activation = () => ContractOperation.ExpandWithInterfacesMarkedAsSubService(
-                config.Binder, 
+                config.Binder,
                 typeof(IIServiceWithBothServiceAndSubServiceAttributes));
             Assert.Throws<ArgumentException>(activation.Invoke);
         }
-        
+
         public class ServiceContractClassInheritsServiceAndSubServiceAttributes
         : IIServiceWithBothServiceAndSubServiceAttributes, IGrpcService
         {
             public void SomeMethod()
             {
             }
         }
-    
+
         [Fact]
         public void WhenServiceContractClassImplementsInterfaceHavingAttributesServiceAndServiceInheritable_Throw()
         {
             var config = BinderConfiguration.Default;
             Action activation = () => ContractOperation.ExpandWithInterfacesMarkedAsSubService(
-                config.Binder, 
+                config.Binder,
                 typeof(ServiceContractClassInheritsServiceAndSubServiceAttributes));
             Assert.Throws<ArgumentException>(activation.Invoke);
         }
 
-        
-        
+        [Fact]
+        public void MultiLevelSubServiceBindings()
+        {
+            // server
+            var serverBinder = new TestServerBinder();
+            Assert.Equal(5, serverBinder.Bind<IOuter>(null!));
+            var methods = string.Join(",", serverBinder.Methods.OrderBy(_ => _));
+
+            Assert.Equal("/other/C,/other/D,/outer/A,/outer/B,/outer/C", methods);
+        }
+
+        [Service("outer")]
+        public interface IOuter : IMiddle, IOtherMiddle
+        {
+            void A();
+        }
+
+        [SubService]
+        public interface IMiddle : IInner
+        {
+            void B();
+        }
+        [SubService]
+        public interface IInner
+        {
+            void C();
+        }
+
+        [Service("other")]
+        public interface IOtherMiddle : IInner
+        {
+            void D();
+        }
+
 #pragma warning disable CS0618 // Empty
         [Theory]
         [InlineData(nameof(IAllOptions.Client_AsyncUnary), typeof(HelloRequest), typeof(HelloReply), MethodType.Unary, (int)ContextKind.CallOptions, (int)ResultKind.Grpc, (int)VoidKind.None, (int)ResultKind.Sync)]
@@ -271,7 +303,7 @@ public void WriteAllMethodSignatures()
             {
                 _output.WriteLine(grp.Key.ToString());
                 _output.WriteLine("");
-                foreach(var (kind, signature) in grp.OrderBy(x => x.Signature))
+                foreach (var (kind, signature) in grp.OrderBy(x => x.Signature))
                     _output.WriteLine(signature);
                 _output.WriteLine("");
             }