feat: public gRPC interface (Hyper.Grpc) (#18)

Author: markovejnovic

.credo.exs

@@ -31,7 +31,7 @@
           "apps/*/test/",
           "apps/*/web/"
         ],
-        excluded: [~r"/_build/", ~r"/deps/", ~r"/node_modules/", "lib/hyper/firecracker/api/operations/", "lib/hyper/firecracker/api/schemas/"]
+        excluded: [~r"/_build/", ~r"/deps/", ~r"/node_modules/", "lib/hyper/firecracker/api/operations/", "lib/hyper/firecracker/api/schemas/", "lib/hyper/grpc/v0/"]
       },
       #
       # Load and configure plugins here:

.github/workflows/ci.yml

@@ -65,6 +65,14 @@ jobs:
       - name: Install dependencies
         run: mix deps.get
 
+      # protoc + the protoc-gen-elixir escript drive the `:grpc_gen` Mix compiler,
+      # which generates the (gitignored) gRPC bindings before the Elixir compiler.
+      - name: Install protoc
+        run: sudo apt-get update && sudo apt-get install -y protobuf-compiler
+
+      - name: Install protoc-gen-elixir
+        run: mix escript.install hex protobuf 0.17.0 --force
+
       - name: Compile (warnings as errors)
         # --force matches the `mix check` alias: re-surfaces warnings even on a
         # cached _build, where an unchanged module would otherwise be skipped.

.gitignore

@@ -40,3 +40,7 @@ docs/superpowers/
 # (priv/firecracker/*.openapi.json) before compile -- see mix.exs gen_firecracker/1.
 /lib/hyper/firecracker/api/operations/
 /lib/hyper/firecracker/api/schemas/
+
+# gRPC bindings are generated from proto/hyper/grpc/v0/hyper.proto before compile
+# -- see the :grpc_gen Mix compiler in mix.exs.
+/lib/hyper/grpc/v0/

docs/grpc.md

@@ -0,0 +1,101 @@
+# gRPC interface
+
+Hyper's native API is BEAM-native (Elixir/Erlang processes calling `Hyper.*`).
+The gRPC interface puts that same machine lifecycle behind a language-agnostic
+contract, so consumers in **any** language -- and off-BEAM services -- can
+create, stop, locate, and list microVMs.
+
+> **v0 -- unstable.** The contract may change without notice during early
+> development. Pin to a commit if you depend on it.
+
+## Configuration
+
+By default, the gRPC interface is **disabled**. You can enable it by editing
+`config/runtime.exs` and setting:
+
+```elixir
+config :hyper, Hyper.Grpc.Config,
+  enabled: true,
+  port: 50051,
+  cred: GRPC.Credential.new(
+    ssl: [certfile: "/path/to/cert.pem", keyfile: "/path/to/key.pem"]
+  )
+```
+
+Note that you can also disable secure mode and use plaintext gRPC:
+
+```elixir
+config :hyper, Hyper.Grpc.Config,
+  enabled: true,
+  port: 50051
+```
+
+> #### TLS Security {: .error}
+>
+> It is **strongly** advised you run gRPC with SSL enabled. Running
+> `Hyper.Grpc` without SSL enabled in production could present a security risk
+> and we strongly suggest against it.
+
+## Client Usage
+
+With `Hyper` running, you can create a new `gRPC` client in your favorite
+language. We will be using _Python_ here:
+
+```python
+import grpc
+from google.protobuf import empty_pb2
+from hyper.grpc.v0 import hyper_pb2, hyper_pb2_grpc
+
+# Plaintext. For TLS, pass grpc.ssl_channel_credentials(ca_pem) to
+# grpc.aio.secure_channel(...) instead.
+client = hyper_pb2_grpc.HyperStub(grpc.aio.insecure_channel("localhost:50051"))
+```
+
+### Creating VMs
+
+You can create new VMs with the `CreateVm` RPC.
+
+```python
+created = await client.CreateVm(
+    hyper_pb2.CreateVmRequest(
+        img_id="img-abc",
+        instance_type=hyper_pb2.INSTANCE_TYPE_DECI,
+        arch=hyper_pb2.ARCHITECTURE_X86_64,
+        # boot_args is optional; omit it for the default kernel cmdline.
+    )
+)
+print(created.vm_id, created.node)
+```
+
+### Listing VMs
+
+You can list running virtual machines with `ListVms`, which takes a
+`google.protobuf.Empty`:
+
+```python
+listed = await client.ListVms(empty_pb2.Empty())
+for vm in listed.vms:
+    print(vm.vm_id, vm.node)
+```
+
+### Getting VM Info
+
+You can query a VM with `GetVm`, which returns the node it runs on:
+
+```python
+info = await client.GetVm(hyper_pb2.GetVmRequest(vm_id=created.vm_id))
+print(info.vm_id, info.node)
+```
+
+### Stopping a VM
+
+You can stop a running VM with `StopVm`, which returns a
+`google.protobuf.Empty`:
+
+```python
+await client.StopVm(hyper_pb2.StopVmRequest(vm_id=created.vm_id))
+```
+
+For full documentation, please read the documentation in the
+[`.proto`](https://github.com/harmont-dev/hyper/blob/main/proto/hyper/grpc/v0/hyper.proto)
+file.

lib/hyper.ex

@@ -51,4 +51,21 @@ defmodule Hyper do
   @doc "Cluster-wide: which node currently runs `vm_id`? `nil` if unknown."
   @spec whereis(Hyper.Vm.id()) :: node() | nil
   def whereis(vm_id), do: Hyper.Cluster.Routing.whereis(vm_id)
+
+  @doc """
+  The vm id for a VM handle -- the pid returned by `create_vm/1`. Resolves on the
+  pid's owning node, so a VM just placed on a remote node is found immediately
+  rather than waiting for the routing CRDT to propagate. `nil` if unknown.
+
+  Returns `nil` (rather than crashing the caller) if the owning node is
+  unreachable -- e.g. it died with a VM just placed on it. In that case the VM
+  died with its host, so "unknown" is the truthful answer. Only `:erpc`'s own
+  transport failures are swallowed; a genuine fault in the lookup still raises.
+  """
+  @spec id(Hyper.Vm.t()) :: Hyper.Vm.id() | nil
+  def id(pid) when is_pid(pid) do
+    :erpc.call(node(pid), Hyper.Cluster.Routing, :id_for, [pid])
+  catch
+    :error, {:erpc, _} -> nil
+  end
 end

lib/hyper/application.ex

@@ -14,19 +14,20 @@ defmodule Hyper.Application do
 
     topologies = Application.get_env(:libcluster, :topologies, [])
 
-    children = [
-      # The image-lineage database. Started first so the rest of the node can
-      # query images/leases on boot.
-      Hyper.Img.Db.Repo,
-      # Form the BEAM cluster (Distributed Erlang) so Horde's `members: :auto`
-      # can discover peer nodes. Gossip strategy in dev - see config/config.exs.
-      {Cluster.Supervisor, [topologies, [name: Hyper.ClusterSupervisor]]},
-      # Cluster-wide CRDTs (VM routing + budget telemetry). Must precede
-      # Hyper.Node so VM registrations and budget advertisements have their
-      # registries on boot.
-      Hyper.Cluster,
-      Hyper.Node
-    ]
+    children =
+      [
+        # The image-lineage database. Started first so the rest of the node can
+        # query images/leases on boot.
+        Hyper.Img.Db.Repo,
+        # Form the BEAM cluster (Distributed Erlang) so Horde's `members: :auto`
+        # can discover peer nodes. Gossip strategy in dev - see config/config.exs.
+        {Cluster.Supervisor, [topologies, [name: Hyper.ClusterSupervisor]]},
+        # Cluster-wide CRDTs (VM routing + budget telemetry). Must precede
+        # Hyper.Node so VM registrations and budget advertisements have their
+        # registries on boot.
+        Hyper.Cluster,
+        Hyper.Node
+      ] ++ Hyper.Grpc.server_children()
 
     Supervisor.start_link(children, strategy: :one_for_one, name: Hyper.Supervisor)
   end

lib/hyper/cluster/routing.ex

@@ -34,4 +34,29 @@ defmodule Hyper.Cluster.Routing do
       [] -> nil
     end
   end
+
+  @doc """
+  The vm_id whose `:supervisor` process is `pid`, or `nil`. Consults the local
+  replica via a registry match spec; intended to be called on the node that owns
+  `pid` (see `Hyper.id/1`).
+  """
+  @spec id_for(pid()) :: Hyper.Vm.id() | nil
+  def id_for(pid) when is_pid(pid) do
+    case Horde.Registry.select(@name, [
+           {{{:"$1", :supervisor}, :"$2", :_}, [{:==, :"$2", pid}], [:"$1"]}
+         ]) do
+      [vm_id | _] -> vm_id
+      [] -> nil
+    end
+  end
+
+  @doc "Every VM the cluster currently knows about, paired with the node it runs on."
+  @spec all() :: [{Hyper.Vm.id(), node()}]
+  def all do
+    @name
+    |> Horde.Registry.select([
+      {{{:"$1", :supervisor}, :"$2", :_}, [], [{{:"$1", :"$2"}}]}
+    ])
+    |> Enum.map(fn {vm_id, pid} -> {vm_id, node(pid)} end)
+  end
 end

lib/hyper/grpc.ex

@@ -0,0 +1,84 @@
+defmodule Hyper.Grpc do
+  @moduledoc """
+  Public gRPC interface to a Hyper cluster.
+
+  The service contract is `hyper.grpc.v0.Hyper` (see
+  `proto/hyper/grpc/v0/hyper.proto`). Any gRPC client, in any language, can
+  create, stop, locate, and list microVMs. Off-BEAM clients generate their own
+  stubs from the `.proto`; BEAM clients can use the generated
+  `Hyper.Grpc.V0.Hyper.Stub` together with `connect/2`.
+  """
+
+  defmodule Config do
+    @moduledoc """
+    gRPC server configuration, read from application env into a struct:
+
+        config :hyper, Hyper.Grpc.Config,
+          enabled: true,
+          port: 50_051,
+          cred: GRPC.Credential.new(ssl: [certfile: "/path/cert.pem", keyfile: "/path/key.pem"])
+
+    Fields:
+
+      * `:enabled` -- whether the server starts. Defaults to `false`.
+      * `:port` -- the listen port. Defaults to `50051`.
+      * `:cred` -- a `GRPC.Credential` for TLS, or `nil` (the default) for
+        plaintext.
+      * `:adapter_opts` -- options forwarded to the server adapter, e.g.
+        `[ip: {0, 0, 0, 0}]`.
+
+    Build the credential where you load your keys (e.g. `config/runtime.exs`);
+    Hyper never reads the filesystem on your behalf.
+
+    > #### Co-located nodes {: .info}
+    >
+    > Every node binds `:port`. Running multiple nodes on one host (e.g. a local
+    > cluster) requires giving each a distinct port via its own config.
+    """
+
+    @default_port 50_051
+
+    defstruct enabled: false, port: @default_port, cred: nil, adapter_opts: []
+
+    @type t :: %__MODULE__{
+            enabled: boolean(),
+            port: :inet.port_number(),
+            cred: GRPC.Credential.t() | nil,
+            adapter_opts: keyword()
+          }
+
+    @doc "Load the gRPC server configuration from application env."
+    @spec load() :: t()
+    def load, do: struct!(__MODULE__, Application.get_env(:hyper, __MODULE__, []))
+
+    @doc """
+    The `GRPC.Server.Supervisor` options for this config: the endpoint and port,
+    plus the TLS credential and adapter options when set.
+    """
+    @spec server_options(t()) :: keyword()
+    def server_options(%__MODULE__{} = config) do
+      [endpoint: Hyper.Grpc.Endpoint, port: config.port, start_server: true]
+      |> put_unless(:cred, config.cred, nil)
+      |> put_unless(:adapter_opts, config.adapter_opts, [])
+    end
+
+    @spec put_unless(keyword(), atom(), term(), term()) :: keyword()
+    defp put_unless(opts, _key, skip, skip), do: opts
+    defp put_unless(opts, key, value, _skip), do: Keyword.put(opts, key, value)
+  end
+
+  @doc """
+  The gRPC server's supervisor child, or `[]` when the server is disabled (the
+  default). Spliced into the app supervision tree by `Hyper.Application`.
+  """
+  @spec server_children() :: [{module(), keyword()}]
+  def server_children do
+    config = Config.load()
+
+    if config.enabled do
+      [{GRPC.Server.Supervisor, Config.server_options(config)}]
+    else
+      []
+    end
+  end
+end