Skip to content

Commit 18fe524

Browse files
author
Vipul Rawat
authored
fix documentation - Readme and gRPC docs (#364)
* add missing grpc doc * remove unused features and links
1 parent 183e1f2 commit 18fe524

File tree

3 files changed

+128
-4
lines changed

3 files changed

+128
-4
lines changed

README.md

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -28,10 +28,11 @@ We will focus ourselves towards deployment in kubernetes and aspire to provide o
2828

2929
1. Simple API syntax
3030
2. REST Standards by default
31-
3. [Configuration management](https://gofr.dev/docs/v1/references/configs)
31+
3. Configuration management
3232
4. Inbuilt Middlewares
33-
5. [Error Management](https://gofr.dev/docs/v1/references/errors)
34-
6. [gRPC support](https://gofr.dev/docs/v1/advanced-guide/grpc)
33+
5. [gRPC support](https://gofr.dev/docs/advanced-guide/grpc)
34+
6. [HTTP service](https://gofr.dev/docs/advanced-guide/http-communication) with support for [Circuit Breaker](https://gofr.dev/docs/advanced-guide/circuit-breaker) and
35+
[Health Check](https://gofr.dev/docs/advanced-guide/monitoring-service-health)
3536

3637
## 👍 Contribute
3738
If you want to say thank you and/or support the active development of GoFr:

docs/advanced-guide/grpc/page.md

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# gRPC
2+
We have already seen how GoFr can help ease the development of HTTP servers, but there are
3+
cases where performance is primiraliy required sacrificing flexibility. In these types of
4+
scenarios gRPC protocol comes into picture. gRPC is an open-source RPC(Remote Procedure Call)
5+
framework initially developed by Google. [Learn more](https://grpc.io/docs/what-is-grpc/introduction/)
6+
7+
## Prerequisites
8+
- Install the `protoc` protocol buffer compilation
9+
- Linux, using `apt` or `apt-get`
10+
```shell
11+
$ apt install -y protobuf-compiler
12+
$ protoc --version # Ensure compiler version is 3+
13+
```
14+
- MacOS, using homebrew
15+
```shell
16+
$ brew install protobuf
17+
$ protoc --version # Ensure compiler version is 3+
18+
```
19+
- Install **Go Puligins** for protocol compiler:
20+
1. Install prtocol compiler plugins for Go
21+
```shell
22+
$ go install google.golang.org/protobuf/cmd/[email protected]
23+
$ go install google.golang.org/grpc/cmd/[email protected]
24+
```
25+
2. Update `PATH` for `protoc` compiler to find the plugins:
26+
```shell
27+
$ export PATH="$PATH:$(go env GOPATH)/bin"
28+
```
29+
30+
## Creating protocol buffers
31+
For a detailed guide, please take a look at the [Tutorial](https://grpc.io/docs/languages/go/basics/) at official gRPC docs.
32+
33+
Fistly, we need to create a `customer.proto` file to define our service and the rpc methods that the service provides.
34+
```protobuf
35+
// Indicates the protocol buffer version that is being used
36+
syntax = "proto3";
37+
// Indicates the go package where the generated file will be produced
38+
option go_package = "";
39+
40+
service CustomerService {
41+
// ...
42+
}
43+
```
44+
Inside the service one can define all the `rpc` methods, specifying the request and responses types.
45+
```protobuf
46+
service CustomerService {
47+
// GetCustomer is a rpc method to get customer data using specific filters
48+
rpc GetCustomer(CustomerFilter) returns(CustomerData) {}
49+
}
50+
```
51+
The `CustomerFilter` and `CustomerData` are two types of messages that will be exchanged between server
52+
and client. Users must define those for protocol buffer to serialize them when making a remote procedure call.
53+
```protobuf
54+
syntax = "proto3";
55+
56+
message CustomerFilter {
57+
int64 id = 1;
58+
string name = 2;
59+
// other fields that can be passed
60+
}
61+
62+
message CustomerData {
63+
int64 id = 1;
64+
string name = 2;
65+
string address = 3;
66+
// other customer releated fields
67+
}
68+
```
69+
70+
Now run the following command to gegnerate go code using the Go gRPC plugins:
71+
```shell
72+
protoc \
73+
--go_out=. \
74+
--go_opt=paths=source_relative \
75+
--go-grpc_out=. \
76+
--go-grpc_opt=paths=source_relative \
77+
customer.proto
78+
```
79+
Above command will generate two files `customer.pb.go` and `customer_grpc.pb.go` and these contain necessary code to perform rpc calls.
80+
In `customer.pb.go` you can find `CustomerService` interface-
81+
```go
82+
// CustomerServiceServer is the server API for CustomerService service.
83+
type CustomerServiceServer interface {
84+
GetCustomer(context.Context, *CustomerFilter) (*CustomerData, error)
85+
}
86+
```
87+
User needs to implement this interface to serve the content to the client calling the method.
88+
```go
89+
package customer
90+
91+
import (
92+
"context"
93+
)
94+
95+
type Handler struct {
96+
// required fields to get the customer data
97+
}
98+
99+
func (h *Handler) GetCustomer(ctx context.Context, filter *CustomerFilter) (*CustomerData, error) {
100+
// get the customer data and handler error
101+
return data, nil
102+
}
103+
```
104+
105+
Lastly to register the gRPC service to the gofr server, user can call the `RegisterCustomerServiceServer` in `customer_grpc.pb.go`
106+
to register the service giving gofr app and the Handler struct.
107+
```go
108+
package main
109+
110+
import (
111+
"gofr.dev/pkg/gofr"
112+
"gofr.dev/examples/grpc-server/customer"
113+
)
114+
115+
func main() {
116+
app := gofr.New()
117+
118+
customer.RegisterCustomerServiceServer(app, customer.Handler{})
119+
120+
app.Run()
121+
}
122+
```
123+
>Note: By default, grpc server will run on port 9000, to customize the port users can set GRPC_PORT config in the .env

docs/navigation.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,9 +19,9 @@ export const navigation = [
1919
{ title: 'Circuit Breaker Support', href: '/docs/advanced-guide/circuit-breaker' },
2020
{ title: 'Monitoring Service Health', href: '/docs/advanced-guide/monitoring-service-health' },
2121
{ title: 'Handling Data Migrations', href: '/docs/advanced-guide/handling-data-migrations' },
22+
{ title: 'Writing gRPC Server', href: '/docs/advanced-guide/grpc' },
2223
// { title: 'Dealing with Remote Files', href: '/docs/advanced-guide/remote-files' },
2324
// { title: 'Supporting OAuth', href: '/docs/advanced-guide/oauth' },
24-
// { title: 'Writing gRPC Server', href: '/docs/advanced-guide/grpc' },
2525
// { title: 'Creating a Static File Server', href: '/docs/advanced-guide/static-file-server' },
2626
// { title: 'WebSockets', href: '/docs/advanced-guide/websockets' },
2727
],

0 commit comments

Comments
 (0)