helloworld

Hello World server and clients

This directory demonstrates all four gRPC method shapes against a service implementing helloworld.proto. The checked-in helloworld_grpc.lua binding and helloworld.pb descriptor set are generated with the globally installed protoc-gen-lua-grpc plugin.

Prerequisites

Install the Lua dependencies for the same Lua interpreter that will run the example. On this Homebrew setup, Lua 5.4 is keg-only, so set its location first:

LUA_DIR=/opt/homebrew/opt/lua@5.4
LUA_BIN="$LUA_DIR/bin/lua"
luarocks --lua-version=5.4 --lua-dir="$LUA_DIR" install --local http
luarocks --lua-version=5.4 --lua-dir="$LUA_DIR" install --local lua-protobuf

Adjust LUA_DIR for another Lua 5.4 installation. LuaJIT is also supported, as long as its own LuaRocks tree contains both dependencies.

Start the included HTTP/2 cleartext (h2c) server in one terminal:

sh examples/helloworld/run-lua.sh \
  examples/helloworld/server.lua 127.0.0.1 50051

The server implements the Greeter service in helloworld.proto. For an HTTPS server, omit insecure = true and provide a TLS context when calling server:listen.

Run the clients

From the repository root:

sh examples/helloworld/run-lua.sh \
  examples/helloworld/unary_client.lua localhost:50051 Ada
sh examples/helloworld/run-lua.sh \
  examples/helloworld/server_stream_client.lua localhost:50051 Ada

The unary client prints one greeting. The server-streaming client prints every HelloReply until the server ends the RPC successfully. The client-streaming client reports how many requests it sent, and the bidi client prints each echo.

Client-streaming and bidirectional calls use the same stream API:

sh examples/helloworld/run-lua.sh examples/helloworld/client_stream_client.lua
sh examples/helloworld/run-lua.sh examples/helloworld/bidi_client.lua

Use stream:send(message) to write an ordered request message, stream:recv() to read an ordered response message, and stream:close_send() to half-close the client send side.

Set GRPC_COMPRESSION=gzip for both the server and a client to exercise gzip message compression. The launcher loads the LuaRocks dependencies for Lua 5.4, including lua-zlib.

The runtime applies a small compatibility shim before loading lua-http so that its HTTP/2 layer accepts standard gRPC trailers.

Run the REST gateway

SayHello has a grpc.lua.http annotation in helloworld.proto. Keep the gRPC server running on port 50051, then start the generated gateway in another terminal:

sh examples/helloworld/run-lua.sh \
  examples/helloworld/gateway.lua localhost:50051 127.0.0.1 8080

Call the RPC through either generated REST binding:

curl http://127.0.0.1:8080/v1/greeter/hello/Ada

curl -X POST http://127.0.0.1:8080/v1/greeter/hello \
  -H 'content-type: application/json' \
  -d '{"name":"Ada"}'

Both requests return {"message":"Hello, Ada!"} from the gRPC server. If the gateway returns gRPC code 14 with Connection refused, verify that the first server command is still running and that the gateway target uses the same host and port.

Regenerate generated files

The global plugin is invoked by name; no --plugin flag is needed when /Users/raezil/go/bin is on PATH.

protoc \
  -I proto \
  -I examples/helloworld \
  --include_imports \
  --descriptor_set_out=examples/helloworld/helloworld.pb \
  --lua-grpc_out=examples/helloworld \
  examples/helloworld/helloworld.proto

The generated Lua binding has no protobuf message definitions; loading the descriptor set before dialing makes the message types available to lua-protobuf. The same generation command reads the HTTP annotation and emits register_greeter_gateway; no second gateway plugin invocation is needed.