Clean up internal calls and Readme (#52)

* Clean up

* clean up sentence

* review sample readme

Author: mjheilmann

README.md

@@ -5,18 +5,14 @@ Server reflection allows servers to assist clients in runtime construction of re
 According to the [GRPC Server Reflection Protocol
 ](https://github.com/grpc/grpc/blob/master/doc/server-reflection.md), the primary usecase for server reflection is to write (typically) command line debugging tools for talking to a grpc server. In particular, such a tool will take in a method and a payload (in human readable text format) send it to the server (typically in binary proto wire format), and then take the response and decode it to text to present to the user.
 
-GrpcReflection, implemented as a gRPC server using `grpc-elixir`, adds reflection support to a `grpc-elixir`  based application.
+GrpcReflection adds reflection support to a `grpc-elixir` based application. It is a supervised application that can support implemented as a gRPC server using `grpc-elixir`, .
 
 ## Installation
 
 The package can be installed by adding `grpc_reflection` to your list of dependencies in `mix.exs`:
 
 ```elixir
-def deps do
-  [
-    {:grpc_reflection, "~> 0.1.0"}
-  ]
-end
+{:grpc_reflection, "~> 0.1.5"}
 ```
 
 Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
@@ -25,37 +21,42 @@ be found at <https://hexdocs.pm/grpc_reflection>.
 
 # Reflection
 
-This is written and tested using [grpcurl](https://github.com/fullstorydev/grpcurl) and postman.  It supports both v1alpha and v1 reflection by using one or both of the provided servers: `rpcReflection.V1.Server` or `rpcReflection.V1alpha.Server`
+This is written and tested using [grpcurl](https://github.com/fullstorydev/grpcurl) and [postman](https://www.postman.com). It supports both v1alpha and v1 reflection by using one or both of the provided servers: `rpcReflection.V1.Server` or `rpcReflection.V1alpha.Server`
 
 ## Enable reflection on your application
 
-1. Rebuild your protos with descriptors on.  Each module and/or service that you would like to expose through reflection must use the protoc elixir-out option `gen_descriptors=true`
+1. Rebuild your protos with descriptors enabled. Each module and/or service that you would like to expose through reflection must use the protoc elixir-out option `gen_descriptors=true`.
+
 1. Create a reflection server
-  ```elixir
-  defmodule Helloworld.Reflection.Server do
-    use GrpcReflection.Server,
-      version: :v1,
-      services: [Helloworld.Greeter.Service]
-  end
-  ```
-  or
-  ```elixir
-  defmodule Helloworld.Reflection.Server2 do
-    use GrpcReflection.Server,
-      version: :v1alpha,
-      services: [Helloworld.Greeter.Service]
-  end
-  ```
-  or both as desired.  `version` is the grpc reflection spec, which can be `v1` or `v1alpha`.  `services` is the services that will be exposed by that server by reflection.  You can expose a service through both services if desired.
+
+   ```elixir
+   defmodule Helloworld.Reflection.Server do
+     use GrpcReflection.Server,
+       version: :v1,
+       services: [Helloworld.Greeter.Service]
+   end
+   ```
+
+   | Config Option | Description                                                            |
+   | ------------- | ---------------------------------------------------------------------- |
+   | version       | Either `:v1` or `:v2` depending on intended client support             |
+   | services      | This is a list of GRPC services that should be included for reflection |
+
 1. Add the reflection supervisor to your supervision tree to host the cached reflection state
-```elixir
-children = [
-  ...other children,
-  GrpcReflection
-]
-```
+
+   ```elixir
+   children = [
+     ...other children,
+     GrpcReflection
+   ]
+   ```
+
 1. Add your servers to your grpc endpoint
 
+   ```elixir
+     run(Helloworld.Reflection.Server)
+   ```
+
 ## interacting with your reflection server
 
 Here are some example `grpcurl` commands and responses excersizing the reflection capabilities
@@ -82,19 +83,19 @@ message HelloReply {
 $ grpcurl -plaintext -format text -d 'name: "faker"' localhost:50051 helloworld.Greeter.SayHello
 message: "Hello faker"
 today: <
-  seconds:1708412184 nanos:671267628 
+  seconds:1708412184 nanos:671267628
 >
 ```
 
 ## Protobuf Version Support
 
-This module is more thoroughly tested with proto3, but it has some testing with proto2.  In either case feedback is appreciated as we approach full proto support in this module.
+This module is more thoroughly tested with proto3, but it has some testing with proto2. In either case feedback is appreciated as we approach full proto support in this module.
 
 ## Application Support
 
 This is **not** an exhaustive list, contributions are appreciated.
 
-| Application  | Reflection version required |
-| ------------- | ------------- |
-| grpcurl  | V1  |
-| postman | V1alpha  |
+| Application | Reflection version required |
+| ----------- | --------------------------- |
+| grpcurl     | V1                          |
+| postman     | V1alpha                     |

examples/helloworld/README.md

@@ -2,36 +2,40 @@
 
 This example is mostly copied directly from `grpc-elixir`, with the exception that this example has:
 
-1. Compiled protos with descriptors on.  This is required for the reflection service to run correctly
+1. Compiled protos with descriptors on. This is required for the reflection service to run correctly
 1. Is running the `GrpcReflection.Server.V1` server in its endpoint
 1. Configured the `GrpcReflection.Server.V1` to include `helloworld` in its services
 
 ## Usage
 
 1. Install deps and compile
+
 ```shell
 $ mix do deps.get, compile
 ```
 
 2. Compile protos
+
 ```shell
 $ ./generate_protos.sh
 ```
 
 3. Run the server
+
 ```shell
 $ mix run --no-halt
 ```
 
 4. Run the client script
+
 ```shell
 $ mix run priv/client.exs
 ```
 
 5. Explore the reflection services
+
 ```shell
 $ grpcurl -v -plaintext 127.0.0.1:50051 list
-grpc.reflection.v1.ServerReflection
 helloworld.Greeter
 
 $ grpcurl -v -plaintext 127.0.0.1:50051 list helloworld.Greeter
@@ -51,7 +55,7 @@ message HelloReply {
 $ grpcurl -plaintext -format text -d 'name: "faker"' localhost:50051 helloworld.Greeter.SayHello
 message: "Hello faker"
 today: <
-  seconds:1708412184 nanos:671267628 
+  seconds:1708412184 nanos:671267628
 >
 ```
 
@@ -60,10 +64,13 @@ today: <
 1. Modify the proto `priv/protos/helloworld.proto`
 2. Install `protoc` [here](https://developers.google.com/protocol-buffers/docs/downloads)
 3. Install `protoc-gen-elixir`
+
 ```
 mix escript.install hex protobuf
 ```
+
 4. Generate the code:
+
 ```shell
 $ ./generate_protos.sh
 ```

examples/helloworld/lib/protos/helloworld.pb.ex

@@ -3,7 +3,7 @@ defmodule Helloworld.HelloRequest do
   The request message containing the user's name.
   """
 
-  use Protobuf, protoc_gen_elixir_version: "0.14.0", syntax: :proto3
+  use Protobuf, protoc_gen_elixir_version: "0.14.1", syntax: :proto3
 
   def descriptor do
     # credo:disable-for-next-line
@@ -45,7 +45,7 @@ defmodule Helloworld.HelloReply do
   The response message containing the greetings
   """
 
-  use Protobuf, protoc_gen_elixir_version: "0.14.0", syntax: :proto3
+  use Protobuf, protoc_gen_elixir_version: "0.14.1", syntax: :proto3
 
   def descriptor do
     # credo:disable-for-next-line
@@ -102,7 +102,7 @@ defmodule Helloworld.Greeter.Service do
   The greeting service definition.
   """
 
-  use GRPC.Service, name: "helloworld.Greeter", protoc_gen_elixir_version: "0.14.0"
+  use GRPC.Service, name: "helloworld.Greeter", protoc_gen_elixir_version: "0.14.1"
 
   def descriptor do
     # credo:disable-for-next-line

examples/helloworld/mix.exs

@@ -21,7 +21,7 @@ defmodule Helloworld.Mixfile do
       {:grpc, "~> 0.9"},
       {:grpc_reflection, path: "../.."},
       {:protobuf, "~> 0.14"},
-      {:dialyxir, "~> 1.1", only: [:dev, :test], runtime: false}
+      {:dialyxir, "~> 1.4", only: [:dev, :test], runtime: false}
     ]
   end
 end

examples/helloworld/mix.lock

@@ -1,8 +1,8 @@
 %{
   "cowboy": {:hex, :cowboy, "2.12.0", "f276d521a1ff88b2b9b4c54d0e753da6c66dd7be6c9fca3d9418b561828a3731", [:make, :rebar3], [{:cowlib, "2.13.0", [hex: :cowlib, repo: "hexpm", optional: false]}, {:ranch, "1.8.0", [hex: :ranch, repo: "hexpm", optional: false]}], "hexpm", "8a7abe6d183372ceb21caa2709bec928ab2b72e18a3911aa1771639bef82651e"},
   "cowlib": {:hex, :cowlib, "2.13.0", "db8f7505d8332d98ef50a3ef34b34c1afddec7506e4ee4dd4a3a266285d282ca", [:make, :rebar3], [], "hexpm", "e1e1284dc3fc030a64b1ad0d8382ae7e99da46c3246b815318a4b848873800a4"},
-  "dialyxir": {:hex, :dialyxir, "1.4.2", "764a6e8e7a354f0ba95d58418178d486065ead1f69ad89782817c296d0d746a5", [:mix], [{:erlex, ">= 0.2.6", [hex: :erlex, repo: "hexpm", optional: false]}], "hexpm", "516603d8067b2fd585319e4b13d3674ad4f314a5902ba8130cd97dc902ce6bbd"},
-  "erlex": {:hex, :erlex, "0.2.6", "c7987d15e899c7a2f34f5420d2a2ea0d659682c06ac607572df55a43753aa12e", [:mix], [], "hexpm", "2ed2e25711feb44d52b17d2780eabf998452f6efda104877a3881c2f8c0c0c75"},
+  "dialyxir": {:hex, :dialyxir, "1.4.5", "ca1571ac18e0f88d4ab245f0b60fa31ff1b12cbae2b11bd25d207f865e8ae78a", [:mix], [{:erlex, ">= 0.2.7", [hex: :erlex, repo: "hexpm", optional: false]}], "hexpm", "b0fb08bb8107c750db5c0b324fa2df5ceaa0f9307690ee3c1f6ba5b9eb5d35c3"},
+  "erlex": {:hex, :erlex, "0.2.7", "810e8725f96ab74d17aac676e748627a07bc87eb950d2b83acd29dc047a30595", [:mix], [], "hexpm", "3ed95f79d1a844c3f6bf0cea61e0d5612a42ce56da9c03f01df538685365efb0"},
   "grpc": {:hex, :grpc, "0.9.0", "1b930a57272d4356ea65969b984c2eb04f3dab81420e1e28f0e6ec04b8f88515", [:mix], [{:castore, "~> 0.1 or ~> 1.0", [hex: :castore, repo: "hexpm", optional: true]}, {:cowboy, "~> 2.10", [hex: :cowboy, repo: "hexpm", optional: false]}, {:cowlib, "~> 2.12", [hex: :cowlib, repo: "hexpm", optional: false]}, {:gun, "~> 2.0", [hex: :gun, repo: "hexpm", optional: false]}, {:jason, ">= 0.0.0", [hex: :jason, repo: "hexpm", optional: true]}, {:mint, "~> 1.5", [hex: :mint, repo: "hexpm", optional: false]}, {:protobuf, "~> 0.11", [hex: :protobuf, repo: "hexpm", optional: false]}, {:telemetry, "~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "7c059698248738fcf7ad551f1d78f4a3d2e0642a72a5834f2a0b0db4b9f3d2b5"},
   "gun": {:hex, :gun, "2.1.0", "b4e4cbbf3026d21981c447e9e7ca856766046eff693720ba43114d7f5de36e87", [:make, :rebar3], [{:cowlib, "2.13.0", [hex: :cowlib, repo: "hexpm", optional: false]}], "hexpm", "52fc7fc246bfc3b00e01aea1c2854c70a366348574ab50c57dfe796d24a0101d"},
   "hpax": {:hex, :hpax, "1.0.2", "762df951b0c399ff67cc57c3995ec3cf46d696e41f0bba17da0518d94acd4aac", [:mix], [], "hexpm", "2f09b4c1074e0abd846747329eaa26d535be0eb3d189fa69d812bfb8bfefd32f"},

lib/grpc_reflection/server/process.ex

@@ -0,0 +1,47 @@
+defmodule GrpcReflection.Server.Process do
+  @moduledoc false
+  require Logger
+
+  def reflect(state_mod, {:list_services, _}) do
+    state_mod.list_services()
+    |> Enum.map(fn name -> %{name: name} end)
+    |> then(fn services ->
+      {:ok, {:list_services_response, %{service: services}}}
+    end)
+  end
+
+  def reflect(state_mod, {:file_containing_symbol, symbol}) do
+    with {:ok, description} <- state_mod.get_by_symbol(symbol) do
+      {:ok, {:file_descriptor_response, description}}
+    end
+  end
+
+  def reflect(state_mod, {:file_by_filename, filename}) do
+    with {:ok, description} <- state_mod.get_by_filename(filename) do
+      {:ok, {:file_descriptor_response, description}}
+    end
+  end
+
+  def reflect(
+        state_mod,
+        {:file_containing_extension,
+         %{containing_type: containing_type, extension_number: _extension_number}}
+      ) do
+    with {:ok, description} <- state_mod.get_by_extension(containing_type) do
+      {:ok, {:file_descriptor_response, description}}
+    end
+  end
+
+  def reflect(state_mod, {:all_extension_numbers_of_type, mod}) do
+    with {:ok, extension_numbers} <- state_mod.get_extension_numbers_by_type(mod) do
+      {:ok,
+       {:all_extension_numbers_response,
+        %{base_type_name: mod, extension_number: extension_numbers}}}
+    end
+  end
+
+  def reflect(_state_mod, message_request) do
+    Logger.warning("received unexpected reflection request: #{inspect(message_request)}")
+    {:error, :unimplemented}
+  end
+end