Skip to content

Update README #62

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Partmedia wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Update README #62

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 33 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,17 +7,29 @@

## Overview

This package defines a [gRPC](https://grpc.io/) client library for Common Lisp.
It wraps gRPC core functions with CFFI calls and uses those core functions to
create and use a client. client.lisp contains all the necessary functions to
This package defines a [gRPC](https://grpc.io/) library for Common Lisp.
It wraps gRPC core functions with CFFI calls.

``client.lisp`` contains all the necessary functions to
create a gRPC client by creating channels (connections between client and
server) and calls (requests to a server).

Currently there is support for synchronous and streaming calls over

SSL, and insecure channels.

Support for implementing gRPC servers is in development.
``server.lisp`` contains a ``run-grpc-server`` function that implements an insecure gRPC server.

If your service is defined by a protobuf, ``protobuf-integration.lisp`` contains a ``run-grpc-proto-server`` function that serves a gRPC/protobuf service.


## Installation

1. Install the gRPC library for your platform (e.g. via a package manager).

2. Clone this repository into [a location findable by ASDF](https://asdf.common-lisp.dev/asdf.html#Configuring-ASDF-to-find-your-systems).

3. In this directory, build the library stub by running ``make``. You may need to make adjustments to the *Makefile* for your platform.

4. Load and use this system in your application, e.g. at a REPL with ``(asdf:load-system "grpc")`` or via a ``defsystem``.

## Usage

Expand Down Expand Up @@ -230,6 +242,21 @@ Will safely cleanup any data leftover in the `call` object.

This example can be found in examples/client/client-insecure.lisp.

### Server

A minimal gRPC service with protobuf integration looks like:

```
; load the protobuf-generated code here

(defmethod cl-protobufs.testing-rpc::say-hello ((request cl-protobufs.testing:hello-request) call)

@cgay cgay Nov 20, 2023

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe say-hello is exported.

The package names don't look right to me. Assuming the server example uses the same :local-nicknames as those in client-insecure.lisp it looks like it should be this instead:

(defmethod testing-rpc:say-hello ((request testing:hello-request) call)

but I haven't actually tried it. WDYT?

@Partmedia Partmedia Nov 20, 2023

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I opted to use the fully-qualified names since someone who is testing this in the REPL would have to use those (as opposed to local-nicknames as part of a defsystem. Let me know your preference and I'll go double check that say-hello is exported.

@Partmedia Partmedia Nov 20, 2023

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Aha, you've been looking at examples/client/client-insecure.lisp which uses examples/client/helloworld.proto which defines package lisp.grpc.integration_testing. However, I've been looking a few lines up in the README, which defines package testing. This is why we disagree about the namespace.

I do think there is value in providing a minimum working example so if there are no objections I'll add that.

(make-hello-reply :name "world")

(defun main ()
(grpc:init-grpc)
(grpc::run-grpc-proto-server "localhost:8080" 'cl-protobufs.testing:greeter))

@cgay cgay Nov 20, 2023

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like we should be exporting run-grpc-server and run-grpc-proto-server. Feel like making another PR? :)

@Partmedia Partmedia Nov 20, 2023

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Happy to go do that.

```

## Further Reading

- See https://grpc.io for more information on gRPC.
Expand Down