Access mode detection (transcode vs grpcweb vs grpc) (#412)

* Detect preflight requests

These typically come from grpcweb clients doing OPTIONS checks for CORS

* Detect client types: grpc, grpcweb, web

This replaces the `http_transcode` member of the `Server.Stream` struct
as transcoding is correlated with being a web client (*not* a grpcweb
client, however!)

Knowing the type of client also allows for detection of when to send
different types of headers, for e.g. CORS

* Add a CORS header injection Interceptor

It an option `:allow` option to define which origins are allowed.

This may be a static string or a function which will be passed the
current `req` and `stream` structs to choose what to allow.

* Reintroduce the boolean http_transcode member of the Stream struct

NOTE: will merge this with commit
c39c834 post-review/discussion.
I am leaving it as a separate commit for now for ease of continued
discussion on the current PR.

* web can be detected in extract_subtype

* change access_type to access_mode, :web to :http_transcoding

this more accurately and directly maps to the grpc terminology, and is
probably clearer.

* default opts to an empty list, whitespace fix

* add tests for the CORS header interceptor

* Assign to a temporary variable and assign that to Stream.http_transcode

* provide access to request headers in the Stream object

* only set cors when the sec-fetch-mode header indicates it

* another test: if there is NO sec-fetch-mode header

* Make access-control-allow-headers configurable, and optional

Only send access-control-allow-headers when the client requests it with
access-control-request-headers and allow the same configurability as
access-control-allow-origin provides

* align variable names with http header names

* Add a CORS example to the README

* format

* Verbage.

Co-authored-by: Paulo Valente <16843419+polvalente@users.noreply.github.com>

* remove default for allow_origin in CORS interceptor

* raise on failed allow_origin type, and test for that

* allow_origin, not allow_header

* test: add missing compile-time test

* chore: format readme

* chore: fix Note bold

* docs: cleanup readme linking

* docs: proper module linking in exdoc

* fix: do not use Keyword.validate due to Elixir 1.12 support

---------

Co-authored-by: Adriano Santos <solid.sistemas@gmail.com>
Co-authored-by: Paulo Valente <16843419+polvalente@users.noreply.github.com>

Author: 3 people

README.md

@@ -15,6 +15,7 @@ An Elixir implementation of [gRPC](http://www.grpc.io/).
 - [Usage](#usage)
   - [Simple RPC](#simple-rpc)
   - [HTTP Transcoding](#http-transcoding)
+  - [CORS](#cors)
   - [Start Application](#start-application)
 - [Features](#features)
 - [Benchmark](#benchmark)
@@ -24,13 +25,13 @@ An Elixir implementation of [gRPC](http://www.grpc.io/).
 
 The package can be installed as:
 
-  ```elixir
-  def deps do
-    [
-      {:grpc, "~> 0.9"}
-    ]
-  end
-  ```
+```elixir
+def deps do
+  [
+    {:grpc, "~> 0.9"}
+  ]
+end
+```
 
 ## Usage
 
@@ -96,7 +97,7 @@ end
 
 We will use this module [in the gRPC server startup section](#start-application).
 
-**__Note:__** For other types of RPC call like streams see [here](interop/lib/interop/server.ex).
+**Note:** For other types of RPC call like streams see [here](interop/lib/interop/server.ex).
 
 ### **HTTP Transcoding**
 
@@ -152,6 +153,7 @@ mix protobuf.generate \
 ```
 
 3. Enable http_transcode option in your Server module
+
 ```elixir
 defmodule Helloworld.Greeter.Server do
   use GRPC.Server,
@@ -167,6 +169,23 @@ end
 
 See full application code in [helloworld_transcoding](examples/helloworld_transcoding) example.
 
+### **CORS**
+
+When accessing gRPC from a browser via HTTP transcoding or gRPC-Web, CORS headers may be required for the browser to allow access to the gRPC endpoint. Adding CORS headers can be done by using `GRPC.Server.Interceptors.CORS` as an interceptor in your `GRPC.Endpoint` module, configuring it as decribed in the module documentation:
+
+Example:
+
+```elixir
+# Define your endpoint
+defmodule Helloworld.Endpoint do
+  use GRPC.Endpoint
+
+  intercept GRPC.Server.Interceptors.Logger
+  intercept GRPC.Server.Interceptors.CORS, allow_origin: "mydomain.io"
+  run Helloworld.Greeter.Server
+end
+```
+
 ### **Start Application**
 
 1. Start gRPC Server in your supervisor tree or Application module:
@@ -231,7 +250,7 @@ The accepted options for configuration are the ones listed on [Mint.HTTP.connect
 - [HTTP Transcoding](https://cloud.google.com/endpoints/docs/grpc/transcoding)
 - [TLS Authentication](https://grpc.io/docs/guides/auth/#supported-auth-mechanisms)
 - [Error handling](https://grpc.io/docs/guides/error/)
-- Interceptors (See [`GRPC.Endpoint`](https://github.com/elixir-grpc/grpc/blob/master/lib/grpc/endpoint.ex))
+- [Interceptors](`GRPC.Endpoint`)
 - [Connection Backoff](https://github.com/grpc/grpc/blob/master/doc/connection-backoff.md)
 - Data compression
 - [gRPC Reflection](https://github.com/elixir-grpc/grpc-reflection)

lib/grpc/server.ex

@@ -152,7 +152,8 @@ defmodule GRPC.Server do
         path = "/#{service_name}/#{name}"
         grpc_type = GRPC.Service.grpc_type(rpc)
 
-        def __call_rpc__(unquote(path), :post, stream) do
+        def __call_rpc__(unquote(path), http_method, stream)
+            when http_method == :post or http_method == :options do
           GRPC.Server.call(
             unquote(service_mod),
             %{
@@ -178,8 +179,7 @@ defmodule GRPC.Server do
                 | service_name: unquote(service_name),
                   method_name: unquote(to_string(name)),
                   grpc_type: unquote(grpc_type),
-                  http_method: unquote(http_method),
-                  http_transcode: unquote(http_transcode)
+                  http_method: unquote(http_method)
               },
               unquote(Macro.escape(put_elem(rpc, 0, func_name))),
               unquote(func_name)
@@ -252,7 +252,7 @@ defmodule GRPC.Server do
            codec: codec,
            adapter: adapter,
            payload: payload,
-           http_transcode: true
+           access_mode: :http_transcoding
          } = stream,
          func_name
        ) do
@@ -271,6 +271,10 @@ defmodule GRPC.Server do
     end
   end
 
+  defp do_handle_request(false, res_stream, %{is_preflight?: true} = stream, func_name) do
+    call_with_interceptors(res_stream, func_name, stream, [])
+  end
+
   defp do_handle_request(
          false,
          res_stream,
@@ -339,7 +343,8 @@ defmodule GRPC.Server do
        ) do
     GRPC.Telemetry.server_span(server, endpoint, func_name, stream, fn ->
       last = fn r, s ->
-        reply = apply(server, func_name, [r, s])
+        # no response is rquired for preflight requests
+        reply = if stream.is_preflight?, do: [], else: apply(server, func_name, [r, s])
 
         if res_stream do
           {:ok, stream}

lib/grpc/server/adapters/cowboy/handler.ex

@@ -28,7 +28,8 @@ defmodule GRPC.Server.Adapters.Cowboy.Handler do
   @type stream_state :: %{
           pid: server_rpc_pid :: pid,
           handling_timer: timeout_timer_ref :: reference,
-          pending_reader: nil | pending_reader
+          pending_reader: nil | pending_reader,
+          access_mode: GRPC.Server.Stream.access_mode()
         }
   @type init_result ::
           {:cowboy_loop, :cowboy_req.req(), stream_state} | {:ok, :cowboy_req.req(), init_state}
@@ -56,10 +57,12 @@ defmodule GRPC.Server.Adapters.Cowboy.Handler do
       |> String.downcase()
       |> String.to_existing_atom()
 
-    with {:ok, sub_type, content_type} <- find_content_type_subtype(req),
+    with {:ok, access_mode, sub_type, content_type} <- find_content_type_subtype(req),
          {:ok, codec} <- find_codec(sub_type, content_type, server),
          {:ok, compressor} <- find_compressor(req, server) do
       stream_pid = self()
+      http_transcode = access_mode == :http_transcoding
+      request_headers = :cowboy_req.headers(req)
 
       stream = %GRPC.Server.Stream{
         server: server,
@@ -69,16 +72,19 @@ defmodule GRPC.Server.Adapters.Cowboy.Handler do
         local: opts[:local],
         codec: codec,
         http_method: http_method,
+        http_request_headers: request_headers,
+        http_transcode: http_transcode,
         compressor: compressor,
-        http_transcode: transcode?(req)
+        is_preflight?: preflight?(req),
+        access_mode: access_mode
       }
 
       server_rpc_pid = :proc_lib.spawn_link(__MODULE__, :call_rpc, [server, route, stream])
       Process.flag(:trap_exit, true)
 
       req = :cowboy_req.set_resp_headers(HTTP2.server_headers(stream), req)
 
-      timeout = :cowboy_req.header("grpc-timeout", req)
+      timeout = Map.get(request_headers, "grpc-timeout")
 
       timer_ref =
         if is_binary(timeout) do
@@ -89,7 +95,16 @@ defmodule GRPC.Server.Adapters.Cowboy.Handler do
           )
         end
 
-      {:cowboy_loop, req, %{pid: server_rpc_pid, handling_timer: timer_ref, pending_reader: nil}}
+      {
+        :cowboy_loop,
+        req,
+        %{
+          pid: server_rpc_pid,
+          handling_timer: timer_ref,
+          pending_reader: nil,
+          access_mode: access_mode
+        }
+      }
     else
       {:error, error} ->
         Logger.error(fn -> inspect(error) end)
@@ -121,12 +136,9 @@ defmodule GRPC.Server.Adapters.Cowboy.Handler do
           content_type
       end
 
-    find_subtype(content_type)
-  end
-
-  defp find_subtype(content_type) do
-    {:ok, subtype} = extract_subtype(content_type)
-    {:ok, subtype, content_type}
+    {:ok, access_mode, subtype} = extract_subtype(content_type)
+    access_mode = resolve_access_mode(req, access_mode, subtype)
+    {:ok, access_mode, subtype, content_type}
   end
 
   defp find_compressor(req, server) do
@@ -600,38 +612,43 @@ defmodule GRPC.Server.Adapters.Cowboy.Handler do
     end
   end
 
-  defp extract_subtype("application/json"), do: {:ok, "json"}
-  defp extract_subtype("application/grpc"), do: {:ok, "proto"}
-  defp extract_subtype("application/grpc+"), do: {:ok, "proto"}
-  defp extract_subtype("application/grpc;"), do: {:ok, "proto"}
-  defp extract_subtype(<<"application/grpc+", rest::binary>>), do: {:ok, rest}
-  defp extract_subtype(<<"application/grpc;", rest::binary>>), do: {:ok, rest}
+  defp extract_subtype("application/json"), do: {:ok, :http_transcoding, "json"}
+  defp extract_subtype("application/grpc"), do: {:ok, :grpc, "proto"}
+  defp extract_subtype("application/grpc+"), do: {:ok, :grpc, "proto"}
+  defp extract_subtype("application/grpc;"), do: {:ok, :grpc, "proto"}
+  defp extract_subtype(<<"application/grpc+", rest::binary>>), do: {:ok, :grpc, rest}
+  defp extract_subtype(<<"application/grpc;", rest::binary>>), do: {:ok, :grpc, rest}
 
-  defp extract_subtype("application/grpc-web"), do: {:ok, "proto"}
-  defp extract_subtype("application/grpc-web+"), do: {:ok, "proto"}
-  defp extract_subtype("application/grpc-web;"), do: {:ok, "proto"}
-  defp extract_subtype("application/grpc-web-text"), do: {:ok, "text"}
-  defp extract_subtype("application/grpc-web+" <> rest), do: {:ok, rest}
-  defp extract_subtype("application/grpc-web-text+" <> rest), do: {:ok, rest}
+  defp extract_subtype("application/grpc-web"), do: {:ok, :grpcweb, "proto"}
+  defp extract_subtype("application/grpc-web+"), do: {:ok, :grpcweb, "proto"}
+  defp extract_subtype("application/grpc-web;"), do: {:ok, :grpcweb, "proto"}
+  defp extract_subtype("application/grpc-web-text"), do: {:ok, :grpcweb, "text"}
+  defp extract_subtype("application/grpc-web+" <> rest), do: {:ok, :grpcweb, rest}
+  defp extract_subtype("application/grpc-web-text+" <> rest), do: {:ok, :grpcweb, rest}
 
   defp extract_subtype(type) do
     Logger.warning("Got unknown content-type #{type}, please create an issue.")
-    {:ok, "proto"}
+    {:ok, :grpc, "proto"}
   end
 
-  defp transcode?(%{version: "HTTP/1.1"}), do: true
+  defp resolve_access_mode(%{version: "HTTP/1.1"}, _detected_access_mode, _type_subtype),
+    do: :http_transcoding
 
-  defp transcode?(req) do
-    case find_content_type_subtype(req) do
-      {:ok, "json", _} -> true
-      _ -> false
-    end
-  end
+  defp resolve_access_mode(%{method: "OPTIONS"}, _detected_access_mode, _type_subtype),
+    do: :grpcweb
+
+  defp resolve_access_mode(_req, detected_access_mode, _type_subtype), do: detected_access_mode
+
+  defp preflight?(%{method: "OPTIONS"}), do: true
+  defp preflight?(_), do: false
 
   defp send_error(req, error, state, reason) do
     trailers = HTTP2.server_trailers(error.status, error.message)
 
-    status = if transcode?(req), do: GRPC.Status.http_code(error.status), else: 200
+    status =
+      if state.access_mode == :http_transcoding,
+        do: GRPC.Status.http_code(error.status),
+        else: 200
 
     if pid = Map.get(state, :pid) do
       exit_handler(pid, reason)