refactor(grpc): rename service Machines->Hyper, RPCs/messages ->Vm

- service hyper.grpc.v0.Machines -> hyper.grpc.v0.Hyper
- RPCs: CreateMachine/StopMachine/GetMachine/ListMachines ->
  CreateVm/StopVm/GetVm/ListVms (handlers create_vm/stop_vm/get_vm/list_vms)
- messages: *Machine{Request,Response} -> *Vm{Request,Response}; Machine -> Vm
  (ListVmsResponse.vms); aligns the wire contract with the BEAM Hyper.create_vm
  terminology and drops the Machine/stutter naming.
Regenerate is automatic (:grpc_gen). Updated server, codec, moduledocs, docs/grpc.md.

Author: markovejnovic

docs/grpc.md

@@ -10,15 +10,15 @@ create, stop, locate, and list microVMs.
 
 ## The contract
 
-The service is `hyper.grpc.v0.Machines`, defined in
+The service is `hyper.grpc.v0.Hyper`, defined in
 [`proto/hyper/grpc/v0/hyper.proto`](https://github.com/harmont-dev/hyper/blob/main/proto/hyper/grpc/v0/hyper.proto):
 
 | RPC            | Purpose                                            | Errors |
 | -------------- | -------------------------------------------------- | ------ |
-| `CreateMachine`| Boot a microVM from an image; returns its `vm_id`. | `INVALID_ARGUMENT` (bad/missing image or enum), `RESOURCE_EXHAUSTED` (no capacity), `UNAVAILABLE` (host lost mid-create) |
-| `StopMachine`  | Tear down a running microVM.                       | `NOT_FOUND` (unknown id), `UNAVAILABLE` (host down) |
-| `GetMachine`   | Which node a microVM runs on.                      | `NOT_FOUND` |
-| `ListMachines` | Every microVM known to the cluster.                | — |
+| `CreateVm`| Boot a microVM from an image; returns its `vm_id`. | `INVALID_ARGUMENT` (bad/missing image or enum), `RESOURCE_EXHAUSTED` (no capacity), `UNAVAILABLE` (host lost mid-create) |
+| `StopVm`  | Tear down a running microVM.                       | `NOT_FOUND` (unknown id), `UNAVAILABLE` (host down) |
+| `GetVm`   | Which node a microVM runs on.                      | `NOT_FOUND` |
+| `ListVms` | Every microVM known to the cluster.                | — |
 
 A machine is addressed by its **`vm_id`** — a URL-safe base64 string the server
 mints at creation. The server is stateless and identical on every node;
@@ -78,7 +78,7 @@ in config.
 ### From any language
 
 Generate a client stub from `proto/hyper/grpc/v0/hyper.proto` with your
-language's gRPC tooling (`protoc`, `buf`, etc.) and call the `Machines` service.
+language's gRPC tooling (`protoc`, `buf`, etc.) and call the `Hyper` service.
 The `.proto` ships in the published package as well as the repo.
 
 ### From the BEAM
@@ -93,18 +93,18 @@ adapter):
 # TLS, verifying the server against a CA bundle
 {:ok, ch} = Hyper.Grpc.connect("hyper.example.com:50051", ca: "/etc/hyper/ca.pem")
 
-{:ok, %Hyper.Grpc.V0.CreateMachineResponse{vm_id: vm_id, node: node}} =
-  Hyper.Grpc.V0.Machines.Stub.create_machine(
+{:ok, %Hyper.Grpc.V0.CreateVmResponse{vm_id: vm_id, node: node}} =
+  Hyper.Grpc.V0.Hyper.Stub.create_vm(
     ch,
-    %Hyper.Grpc.V0.CreateMachineRequest{
+    %Hyper.Grpc.V0.CreateVmRequest{
       img_id: "img-abc",
       instance_type: :INSTANCE_TYPE_DECI
     }
   )
 
 {:ok, _} =
-  Hyper.Grpc.V0.Machines.Stub.stop_machine(
+  Hyper.Grpc.V0.Hyper.Stub.stop_vm(
     ch,
-    %Hyper.Grpc.V0.StopMachineRequest{vm_id: vm_id}
+    %Hyper.Grpc.V0.StopVmRequest{vm_id: vm_id}
   )
 ```

lib/hyper/grpc.ex

@@ -2,11 +2,11 @@ defmodule Hyper.Grpc do
   @moduledoc """
   Public gRPC interface to a Hyper cluster.
 
-  The service contract is `hyper.grpc.v0.Machines` (see
+  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.Machines.Stub` together with `connect/2`.
+  `Hyper.Grpc.V0.Hyper.Stub` together with `connect/2`.
 
   > #### v0 {: .warning}
   >
@@ -25,9 +25,9 @@ defmodule Hyper.Grpc do
 
       {:ok, ch} = Hyper.Grpc.connect("hyper.example.com:50051", ca: "/etc/hyper/ca.pem")
       {:ok, reply} =
-        Hyper.Grpc.V0.Machines.Stub.create_machine(
+        Hyper.Grpc.V0.Hyper.Stub.create_vm(
           ch,
-          %Hyper.Grpc.V0.CreateMachineRequest{img_id: "img-abc"}
+          %Hyper.Grpc.V0.CreateVmRequest{img_id: "img-abc"}
         )
   """
 

lib/hyper/grpc/codec.ex

@@ -9,12 +9,12 @@ defmodule Hyper.Grpc.Codec do
   """
 
   alias Hyper.Grpc.V0.{
-    CreateMachineRequest,
-    CreateMachineResponse,
-    GetMachineResponse,
-    ListMachinesResponse,
-    Machine,
-    StopMachineResponse
+    CreateVmRequest,
+    CreateVmResponse,
+    GetVmResponse,
+    ListVmsResponse,
+    StopVmResponse,
+    Vm
   }
 
   alias Hyper.Vm.Spec
@@ -54,11 +54,11 @@ defmodule Hyper.Grpc.Codec do
   @typep arch_enum :: :ARCHITECTURE_X86_64 | :ARCHITECTURE_AARCH64
 
   @doc "Convert an inbound request message to a domain value."
-  @spec from_grpc(CreateMachineRequest.t()) :: {:ok, Spec.t()} | {:error, term()}
-  def from_grpc(%CreateMachineRequest{img_id: img_id}) when img_id in [nil, ""],
+  @spec from_grpc(CreateVmRequest.t()) :: {:ok, Spec.t()} | {:error, term()}
+  def from_grpc(%CreateVmRequest{img_id: img_id}) when img_id in [nil, ""],
     do: {:error, :missing_img_id}
 
-  def from_grpc(%CreateMachineRequest{} = req) do
+  def from_grpc(%CreateVmRequest{} = req) do
     with {:ok, type} <- instance_type(req.instance_type),
          {:ok, arch} <- arch(req.arch) do
       {:ok,
@@ -72,20 +72,20 @@ defmodule Hyper.Grpc.Codec do
   end
 
   @doc "Convert a domain result to an outbound response message, or an error to `GRPC.RPCError`."
-  @spec to_grpc({:created, Hyper.Vm.id(), node()}) :: CreateMachineResponse.t()
+  @spec to_grpc({:created, Hyper.Vm.id(), node()}) :: CreateVmResponse.t()
   def to_grpc({:created, vm_id, node}) when is_binary(vm_id),
-    do: %CreateMachineResponse{vm_id: vm_id, node: to_string(node)}
+    do: %CreateVmResponse{vm_id: vm_id, node: to_string(node)}
 
-  @spec to_grpc({:located, Hyper.Vm.id(), node()}) :: GetMachineResponse.t()
+  @spec to_grpc({:located, Hyper.Vm.id(), node()}) :: GetVmResponse.t()
   def to_grpc({:located, vm_id, node}),
-    do: %GetMachineResponse{vm_id: vm_id, node: to_string(node)}
+    do: %GetVmResponse{vm_id: vm_id, node: to_string(node)}
 
-  @spec to_grpc({:machines, [{Hyper.Vm.id(), node()}]}) :: ListMachinesResponse.t()
-  def to_grpc({:machines, machines}),
-    do: %ListMachinesResponse{machines: Enum.map(machines, &machine/1)}
+  @spec to_grpc({:vms, [{Hyper.Vm.id(), node()}]}) :: ListVmsResponse.t()
+  def to_grpc({:vms, vms}),
+    do: %ListVmsResponse{vms: Enum.map(vms, &vm/1)}
 
-  @spec to_grpc(:stopped) :: StopMachineResponse.t()
-  def to_grpc(:stopped), do: %StopMachineResponse{}
+  @spec to_grpc(:stopped) :: StopVmResponse.t()
+  def to_grpc(:stopped), do: %StopVmResponse{}
 
   @spec to_grpc({:error, term()}) :: GRPC.RPCError.t()
   def to_grpc({:error, reason}), do: rpc_error(reason)
@@ -100,8 +100,8 @@ defmodule Hyper.Grpc.Codec do
   def to_grpc({:exit, {:nodedown, _}}), do: rpc_error(:machine_unreachable)
   def to_grpc({:exit, reason}), do: rpc_error({:stop_failed, reason})
 
-  @spec machine({Hyper.Vm.id(), node()}) :: Machine.t()
-  defp machine({vm_id, node}), do: %Machine{vm_id: vm_id, node: to_string(node)}
+  @spec vm({Hyper.Vm.id(), node()}) :: Vm.t()
+  defp vm({vm_id, node}), do: %Vm{vm_id: vm_id, node: to_string(node)}
 
   @spec instance_type(nil) :: {:ok, :base}
   defp instance_type(nil), do: {:ok, :base}
@@ -121,10 +121,10 @@ defmodule Hyper.Grpc.Codec do
     do: GRPC.RPCError.exception(:invalid_argument, "img_id is required")
 
   defp rpc_error(:not_found),
-    do: GRPC.RPCError.exception(:not_found, "no such machine")
+    do: GRPC.RPCError.exception(:not_found, "no such VM")
 
   defp rpc_error(:machine_unreachable),
-    do: GRPC.RPCError.exception(:unavailable, "machine's host node is unreachable")
+    do: GRPC.RPCError.exception(:unavailable, "VM's host node is unreachable")
 
   defp rpc_error(reason) when reason in [:no_capacity, :exhausted],
     do: GRPC.RPCError.exception(:resource_exhausted, "no capacity")

lib/hyper/grpc/server.ex

@@ -1,6 +1,6 @@
 defmodule Hyper.Grpc.Server do
   @moduledoc """
-  gRPC handler for `hyper.grpc.v0.Machines`. A thin translation layer: each RPC
+  gRPC handler for `hyper.grpc.v0.Hyper`. A thin translation layer: each RPC
   maps its request to a domain value via `Hyper.Grpc.Codec.from_grpc/1`, calls
   the existing `Hyper` BEAM API, and maps the result back with
   `Hyper.Grpc.Codec.to_grpc/1` (raising the `GRPC.RPCError` it returns on error).
@@ -10,24 +10,23 @@ defmodule Hyper.Grpc.Server do
   so a call landing on any node is correct.
   """
 
-  use GRPC.Server, service: Hyper.Grpc.V0.Machines.Service
+  use GRPC.Server, service: Hyper.Grpc.V0.Hyper.Service
 
   alias Hyper.Grpc.Codec
 
   alias Hyper.Grpc.V0.{
-    CreateMachineRequest,
-    CreateMachineResponse,
-    GetMachineRequest,
-    GetMachineResponse,
-    ListMachinesRequest,
-    ListMachinesResponse,
-    StopMachineRequest,
-    StopMachineResponse
+    CreateVmRequest,
+    CreateVmResponse,
+    GetVmRequest,
+    GetVmResponse,
+    ListVmsRequest,
+    ListVmsResponse,
+    StopVmRequest,
+    StopVmResponse
   }
 
-  @spec create_machine(CreateMachineRequest.t(), GRPC.Server.Stream.t()) ::
-          CreateMachineResponse.t()
-  def create_machine(%CreateMachineRequest{} = req, _stream) do
+  @spec create_vm(CreateVmRequest.t(), GRPC.Server.Stream.t()) :: CreateVmResponse.t()
+  def create_vm(%CreateVmRequest{} = req, _stream) do
     with {:ok, spec} <- Codec.from_grpc(req),
          {:ok, pid} <- Hyper.create_vm(spec),
          vm_id when is_binary(vm_id) <- Hyper.id(pid) do
@@ -40,27 +39,24 @@ defmodule Hyper.Grpc.Server do
     end
   end
 
-  @spec stop_machine(StopMachineRequest.t(), GRPC.Server.Stream.t()) ::
-          StopMachineResponse.t()
-  def stop_machine(%StopMachineRequest{vm_id: vm_id}, _stream) do
+  @spec stop_vm(StopVmRequest.t(), GRPC.Server.Stream.t()) :: StopVmResponse.t()
+  def stop_vm(%StopVmRequest{vm_id: vm_id}, _stream) do
     Hyper.Node.FireVMM.State.stop(vm_id)
     Codec.to_grpc(:stopped)
   catch
     :exit, reason -> raise Codec.to_grpc({:exit, reason})
   end
 
-  @spec get_machine(GetMachineRequest.t(), GRPC.Server.Stream.t()) ::
-          GetMachineResponse.t()
-  def get_machine(%GetMachineRequest{vm_id: vm_id}, _stream) do
+  @spec get_vm(GetVmRequest.t(), GRPC.Server.Stream.t()) :: GetVmResponse.t()
+  def get_vm(%GetVmRequest{vm_id: vm_id}, _stream) do
     case Hyper.whereis(vm_id) do
       nil -> raise Codec.to_grpc({:error, :not_found})
       node -> Codec.to_grpc({:located, vm_id, node})
     end
   end
 
-  @spec list_machines(ListMachinesRequest.t(), GRPC.Server.Stream.t()) ::
-          ListMachinesResponse.t()
-  def list_machines(%ListMachinesRequest{}, _stream) do
-    Codec.to_grpc({:machines, Hyper.Cluster.Routing.all()})
+  @spec list_vms(ListVmsRequest.t(), GRPC.Server.Stream.t()) :: ListVmsResponse.t()
+  def list_vms(%ListVmsRequest{}, _stream) do
+    Codec.to_grpc({:vms, Hyper.Cluster.Routing.all()})
   end
 end

proto/hyper/grpc/v0/hyper.proto

@@ -5,21 +5,21 @@ package hyper.grpc.v0;
 // Hyper microVM orchestration.
 //
 // v0: unstable. This contract may change without notice during early
-// development. Every machine is addressed by its `vm_id`, a URL-safe base64
+// development. Every VM is addressed by its `vm_id`, a URL-safe base64
 // string minted by the server at creation time.
-service Machines {
+service Hyper {
   // Create and boot a microVM from an image. Placement is cluster-wide and
   // automatic. Returns the minted vm_id and the node the guest booted on.
-  rpc CreateMachine(CreateMachineRequest) returns (CreateMachineResponse);
+  rpc CreateVm(CreateVmRequest) returns (CreateVmResponse);
 
   // Stop and tear down a running microVM. NOT_FOUND if no such vm_id runs.
-  rpc StopMachine(StopMachineRequest) returns (StopMachineResponse);
+  rpc StopVm(StopVmRequest) returns (StopVmResponse);
 
   // Locate a microVM: the node it currently runs on. NOT_FOUND if unknown.
-  rpc GetMachine(GetMachineRequest) returns (GetMachineResponse);
+  rpc GetVm(GetVmRequest) returns (GetVmResponse);
 
   // List every microVM currently known to the cluster.
-  rpc ListMachines(ListMachinesRequest) returns (ListMachinesResponse);
+  rpc ListVms(ListVmsRequest) returns (ListVmsResponse);
 }
 
 // Fixed (vCPU, memory, disk) sizes, like cloud instance classes.
@@ -43,40 +43,40 @@ enum Architecture {
   ARCHITECTURE_AARCH64 = 1;
 }
 
-message CreateMachineRequest {
+message CreateVmRequest {
   string img_id = 1;                        // required: content-addressed image id
   optional InstanceType instance_type = 2;  // unset -> server default (base)
   optional Architecture arch = 3;           // unset -> resolve to the node's arch
   optional string boot_args = 4;            // unset -> default kernel cmdline
 }
 
-message CreateMachineResponse {
+message CreateVmResponse {
   string vm_id = 1;
   string node = 2;  // erlang node the guest booted on
 }
 
-message StopMachineRequest {
+message StopVmRequest {
   string vm_id = 1;
 }
 
-message StopMachineResponse {}
+message StopVmResponse {}
 
-message GetMachineRequest {
+message GetVmRequest {
   string vm_id = 1;
 }
 
-message GetMachineResponse {
+message GetVmResponse {
   string vm_id = 1;
   string node = 2;
 }
 
-message ListMachinesRequest {}
+message ListVmsRequest {}
 
-message ListMachinesResponse {
-  repeated Machine machines = 1;
+message ListVmsResponse {
+  repeated Vm vms = 1;
 }
 
-message Machine {
+message Vm {
   string vm_id = 1;
   string node = 2;
 }