To add the library to your Golang application use the following command:
-go get github.com/libopenstorage/grpc-framework@v0.0.8
+go get github.com/libopenstorage/grpc-framework@v0.1.0
Also, use the following container version on your builds:
-quay.io/openstorage/grpc-framework:v0.0.9
+quay.io/openstorage/grpc-framework:v0.1.0
Here is an example:
PROTO_FILE = ./api/hello.proto
@@ -706,7 +706,7 @@ Usage&
-e "PROTO_USER=$(shell id -u)" \
-e "PROTO_GROUP=$(shell id -g)" \
-e "PATH=/bin:/usr/bin:/usr/local/bin:/go/bin:/usr/local/go/bin" \
- quay.io/openstorage/grpc-framework:v0.0.9 \
+ quay.io/openstorage/grpc-framework:v0.1.0 \
make docker-proto
docker-proto:
diff --git a/docs/intro/index.html b/docs/intro/index.html
index 0958dbb..685ec4f 100644
--- a/docs/intro/index.html
+++ b/docs/intro/index.html
@@ -9,7 +9,7 @@
-
+
@@ -841,7 +841,7 @@ Containerize tools
-
+
diff --git a/docs/reference/hello.pb/index.html b/docs/reference/hello.pb/index.html
index c9b8b0a..0f2e26d 100644
--- a/docs/reference/hello.pb/index.html
+++ b/docs/reference/hello.pb/index.html
@@ -9,7 +9,7 @@
-
+
diff --git a/docs/reference/intro/index.html b/docs/reference/intro/index.html
index 4b953c7..4e0672d 100644
--- a/docs/reference/intro/index.html
+++ b/docs/reference/intro/index.html
@@ -9,7 +9,7 @@
-
+
diff --git a/docs/reference/rate-limiter/index.html b/docs/reference/rate-limiter/index.html
index 8e80ac3..e613534 100644
--- a/docs/reference/rate-limiter/index.html
+++ b/docs/reference/rate-limiter/index.html
@@ -9,7 +9,7 @@
-
+
diff --git a/docs/reference/rest/index.html b/docs/reference/rest/index.html
index 71ed8ae..9f201dd 100644
--- a/docs/reference/rest/index.html
+++ b/docs/reference/rest/index.html
@@ -9,7 +9,7 @@
-
+
diff --git a/docs/reference/security/audit/index.html b/docs/reference/security/audit/index.html
index c6d1035..d1f2918 100644
--- a/docs/reference/security/audit/index.html
+++ b/docs/reference/security/audit/index.html
@@ -9,7 +9,7 @@
-
+
diff --git a/docs/reference/security/authentication/index.html b/docs/reference/security/authentication/index.html
index 2a7f7d2..bfc2113 100644
--- a/docs/reference/security/authentication/index.html
+++ b/docs/reference/security/authentication/index.html
@@ -9,7 +9,7 @@
-
+
diff --git a/docs/reference/security/authorization/index.html b/docs/reference/security/authorization/index.html
index 570ca2d..d0933f0 100644
--- a/docs/reference/security/authorization/index.html
+++ b/docs/reference/security/authorization/index.html
@@ -9,7 +9,7 @@
-
+
diff --git a/docs/reference/security/intro/index.html b/docs/reference/security/intro/index.html
index 0fb7ce1..9f9461e 100644
--- a/docs/reference/security/intro/index.html
+++ b/docs/reference/security/intro/index.html
@@ -9,7 +9,7 @@
-
+
diff --git a/docs/reference/security/tls/index.html b/docs/reference/security/tls/index.html
index 6475872..0b537cf 100644
--- a/docs/reference/security/tls/index.html
+++ b/docs/reference/security/tls/index.html
@@ -9,7 +9,7 @@
-
+
diff --git a/docs/reference/style-guide/index.html b/docs/reference/style-guide/index.html
index 5be99dd..f074d47 100644
--- a/docs/reference/style-guide/index.html
+++ b/docs/reference/style-guide/index.html
@@ -9,7 +9,7 @@
-
+
diff --git a/docs/search/search_index.json b/docs/search/search_index.json
index fe268af..e1d76b7 100644
--- a/docs/search/search_index.json
+++ b/docs/search/search_index.json
@@ -1 +1 @@
-{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Welcome to grpc-framework \u00b6 The grpc-framework enables Golang developers to create secure gRPC applications easily. The project provides developers with the following features: Generate REST and swagger APIs Generate Markdown documentation Security Authentication (OIDC and JWT supported) Authorization (RBAC / Role Based Access Control) TLS support Auditing Rate Limiter Metrics for Prometheus API Logging proto/gRPC build container And more... Usage \u00b6 To add the library to your Golang application use the following command: go get github.com/libopenstorage/grpc-framework@v0.0.8 Also, use the following container version on your builds: quay.io/openstorage/grpc-framework:v0.0.9 Here is an example: PROTO_FILE = ./api/hello.proto proto: docker run \\ --privileged --rm \\ -v $(shell pwd):/go/src/code \\ -e \"GOPATH=/go\" \\ -e \"DOCKER_PROTO=yes\" \\ -e \"PROTO_USER=$(shell id -u)\" \\ -e \"PROTO_GROUP=$(shell id -g)\" \\ -e \"PATH=/bin:/usr/bin:/usr/local/bin:/go/bin:/usr/local/go/bin\" \\ quay.io/openstorage/grpc-framework:v0.0.9 \\ make docker-proto docker-proto: ifndef DOCKER_PROTO $(error Do not run directly. Run 'make proto' instead.) endif grpcfw $(PROTO_FILE) grpcfw-rest $(PROTO_FILE) grpcfw-doc $(PROTO_FILE) We are working on a tutorial, but in the meantime, please check out the example test program . Projects Used \u00b6 grpc-framework uses the following excellent projects in the framework: gRPC Golang gRPC REST Gateway Golang JWT Logging with logrus Generate Markdown documentation","title":"Home"},{"location":"#welcome-to-grpc-framework","text":"The grpc-framework enables Golang developers to create secure gRPC applications easily. The project provides developers with the following features: Generate REST and swagger APIs Generate Markdown documentation Security Authentication (OIDC and JWT supported) Authorization (RBAC / Role Based Access Control) TLS support Auditing Rate Limiter Metrics for Prometheus API Logging proto/gRPC build container And more...","title":"Welcome to grpc-framework"},{"location":"#usage","text":"To add the library to your Golang application use the following command: go get github.com/libopenstorage/grpc-framework@v0.0.8 Also, use the following container version on your builds: quay.io/openstorage/grpc-framework:v0.0.9 Here is an example: PROTO_FILE = ./api/hello.proto proto: docker run \\ --privileged --rm \\ -v $(shell pwd):/go/src/code \\ -e \"GOPATH=/go\" \\ -e \"DOCKER_PROTO=yes\" \\ -e \"PROTO_USER=$(shell id -u)\" \\ -e \"PROTO_GROUP=$(shell id -g)\" \\ -e \"PATH=/bin:/usr/bin:/usr/local/bin:/go/bin:/usr/local/go/bin\" \\ quay.io/openstorage/grpc-framework:v0.0.9 \\ make docker-proto docker-proto: ifndef DOCKER_PROTO $(error Do not run directly. Run 'make proto' instead.) endif grpcfw $(PROTO_FILE) grpcfw-rest $(PROTO_FILE) grpcfw-doc $(PROTO_FILE) We are working on a tutorial, but in the meantime, please check out the example test program .","title":"Usage"},{"location":"#projects-used","text":"grpc-framework uses the following excellent projects in the framework: gRPC Golang gRPC REST Gateway Golang JWT Logging with logrus Generate Markdown documentation","title":"Projects Used"},{"location":"about/","text":"About \u00b6 The software was first created for our OpenStorage project, but we then decided to make it its own separate framework so that other projects can use it easily. See also: KubeCon 2019 San Diego / Securing Your Services with Authentication, Authorization, and RBAC in gRPC","title":"About"},{"location":"about/#about","text":"The software was first created for our OpenStorage project, but we then decided to make it its own separate framework so that other projects can use it easily. See also: KubeCon 2019 San Diego / Securing Your Services with Authentication, Authorization, and RBAC in gRPC","title":"About"},{"location":"intro/","text":"Introduction \u00b6 The following will guide through some of the features provided by this framework Containerize tools \u00b6 The framework provides the latest tools for generating gRPC as a single container called quay.io/openstorage/grpc-framework . Here is a sample set of targets for a Makefile on how the container can be used to generate gRPC code from your protocol buffer files. PROTO_FILE = ./api/hello.proto proto: docker run \\ --privileged --rm \\ -v $(shell pwd):/go/src/code \\ -e \"GOPATH=/go\" \\ -e \"DOCKER_PROTO=yes\" \\ -e \"PROTO_USER=$(shell id -u)\" \\ -e \"PROTO_GROUP=$(shell id -g)\" \\ -e \"PATH=/bin:/usr/bin:/usr/local/bin:/go/bin:/usr/local/go/bin\" \\ quay.io/openstorage/grpc-framework:latest \\ make docker-proto docker-proto: ifndef DOCKER_PROTO $(error Do not run directly. Run 'make proto' instead.) endif grpcfw $(PROTO_FILE) grpcfw-rest $(PROTO_FILE) grpcfw-doc $(PROTO_FILE) The framework provides a set of grpcfw* programs in a container, to help with the generation of the sources from the protocol buffers file. Generate REST and swagger APIs \u00b6 The framework utilizes the grpc-gateway to generate a REST interface for your application. The framework will setup and start the HTTP server and automatically connect it to your gRPC server. The REST APIs will be served by the HTTP server which are then forwared to the gRPC server to be handled. The framework will also generate a swagger API file which can be provided to REST client developers. The following is an example of how a gRPC service can be used from a REST client. // The greeting service definition. service HelloGreeter { // Sends a greeting rpc SayHello (HelloGreeterSayHelloRequest) returns (HelloGreeterSayHelloResponse) { option(google.api.http) = { post: \"/v1/greeter/sayhello\" body: \"*\" }; } } // The request message containing the user's name. message HelloGreeterSayHelloRequest { string name = 1; } // The response message containing the greetings message HelloGreeterSayHelloResponse { string message = 1; } Here, the grpc-gateway would use the information located in the option(google.api.http) section of your gRPC rpc to generate a REST call. To enable the REST server for your application, you would need to enable it in your configuration: import( \"github.com/libopenstorage/grpc-framework/server\" ) ... grpcConfig := &server.ServerConfig{ Name: \"hello\", Address: \"127.0.0.1:9009\", Socket: \"/tmp/hello-server.sock\", AuditOutput: os.Stdout, AccessOutput: os.Stdout, } restPort := \"9010\" grpcConfig.WithDefaultRestServer(restPort) ... Once the server is started, you can then use a REST client to send commands to your application: $ curl -X POST -d '{ \"name\": \"Luis\" }' \\ --silent http://localhost:9010/v1/greeter/sayhello | jq { \"message\": \"Hello, Luis\" } Generate Markdown documentation \u00b6 The framework also provides protoc-doc to generate Markdown documentation from the comments on your protocol buffers files. Security \u00b6 The framework makes it simple to add authentication, authorization, and TLS to secure your application. Authentication and RBAC authorization are provided by a set of interceptors in the gRPC server. Authentication (OIDC and JWT supported) \u00b6 The framework support shared secret, public-private key, or OpenID Connect authentication models. Authorization \u00b6 The framework provides (RBAC) role based access control for gRPC services as well as a generic resource authorization model. TLS support \u00b6 The framework provides TLS server support. Auditing \u00b6 The framework logs access to the APIs by recording identifying information read from the authentication token of the caller. This is done by an interceptor that is automatically installed by the framework when authentication is enabled on the gRPC server. Rate Limiter \u00b6 The framework provides rate limiter support with a plan for future releases tor provide the rate limit per user. Metrics for Prometheus \u00b6 Support for Prometheus is provided by go-grpc-prometheus . API Logging \u00b6 Like auditing, a logging interceptor is provided which can provide rountrip information for API services. proto/gRPC build container \u00b6 All tools and updated libraries are all provided by a container to make it simple to utilize on your projects.","title":"Introduction"},{"location":"intro/#introduction","text":"The following will guide through some of the features provided by this framework","title":"Introduction"},{"location":"intro/#containerize-tools","text":"The framework provides the latest tools for generating gRPC as a single container called quay.io/openstorage/grpc-framework . Here is a sample set of targets for a Makefile on how the container can be used to generate gRPC code from your protocol buffer files. PROTO_FILE = ./api/hello.proto proto: docker run \\ --privileged --rm \\ -v $(shell pwd):/go/src/code \\ -e \"GOPATH=/go\" \\ -e \"DOCKER_PROTO=yes\" \\ -e \"PROTO_USER=$(shell id -u)\" \\ -e \"PROTO_GROUP=$(shell id -g)\" \\ -e \"PATH=/bin:/usr/bin:/usr/local/bin:/go/bin:/usr/local/go/bin\" \\ quay.io/openstorage/grpc-framework:latest \\ make docker-proto docker-proto: ifndef DOCKER_PROTO $(error Do not run directly. Run 'make proto' instead.) endif grpcfw $(PROTO_FILE) grpcfw-rest $(PROTO_FILE) grpcfw-doc $(PROTO_FILE) The framework provides a set of grpcfw* programs in a container, to help with the generation of the sources from the protocol buffers file.","title":"Containerize tools"},{"location":"intro/#generate-rest-and-swagger-apis","text":"The framework utilizes the grpc-gateway to generate a REST interface for your application. The framework will setup and start the HTTP server and automatically connect it to your gRPC server. The REST APIs will be served by the HTTP server which are then forwared to the gRPC server to be handled. The framework will also generate a swagger API file which can be provided to REST client developers. The following is an example of how a gRPC service can be used from a REST client. // The greeting service definition. service HelloGreeter { // Sends a greeting rpc SayHello (HelloGreeterSayHelloRequest) returns (HelloGreeterSayHelloResponse) { option(google.api.http) = { post: \"/v1/greeter/sayhello\" body: \"*\" }; } } // The request message containing the user's name. message HelloGreeterSayHelloRequest { string name = 1; } // The response message containing the greetings message HelloGreeterSayHelloResponse { string message = 1; } Here, the grpc-gateway would use the information located in the option(google.api.http) section of your gRPC rpc to generate a REST call. To enable the REST server for your application, you would need to enable it in your configuration: import( \"github.com/libopenstorage/grpc-framework/server\" ) ... grpcConfig := &server.ServerConfig{ Name: \"hello\", Address: \"127.0.0.1:9009\", Socket: \"/tmp/hello-server.sock\", AuditOutput: os.Stdout, AccessOutput: os.Stdout, } restPort := \"9010\" grpcConfig.WithDefaultRestServer(restPort) ... Once the server is started, you can then use a REST client to send commands to your application: $ curl -X POST -d '{ \"name\": \"Luis\" }' \\ --silent http://localhost:9010/v1/greeter/sayhello | jq { \"message\": \"Hello, Luis\" }","title":"Generate REST and swagger APIs"},{"location":"intro/#generate-markdown-documentation","text":"The framework also provides protoc-doc to generate Markdown documentation from the comments on your protocol buffers files.","title":"Generate Markdown documentation"},{"location":"intro/#security","text":"The framework makes it simple to add authentication, authorization, and TLS to secure your application. Authentication and RBAC authorization are provided by a set of interceptors in the gRPC server.","title":"Security"},{"location":"intro/#authentication-oidc-and-jwt-supported","text":"The framework support shared secret, public-private key, or OpenID Connect authentication models.","title":"Authentication (OIDC and JWT supported)"},{"location":"intro/#authorization","text":"The framework provides (RBAC) role based access control for gRPC services as well as a generic resource authorization model.","title":"Authorization"},{"location":"intro/#tls-support","text":"The framework provides TLS server support.","title":"TLS support"},{"location":"intro/#auditing","text":"The framework logs access to the APIs by recording identifying information read from the authentication token of the caller. This is done by an interceptor that is automatically installed by the framework when authentication is enabled on the gRPC server.","title":"Auditing"},{"location":"intro/#rate-limiter","text":"The framework provides rate limiter support with a plan for future releases tor provide the rate limit per user.","title":"Rate Limiter"},{"location":"intro/#metrics-for-prometheus","text":"Support for Prometheus is provided by go-grpc-prometheus .","title":"Metrics for Prometheus"},{"location":"intro/#api-logging","text":"Like auditing, a logging interceptor is provided which can provide rountrip information for API services.","title":"API Logging"},{"location":"intro/#protogrpc-build-container","text":"All tools and updated libraries are all provided by a container to make it simple to utilize on your projects.","title":"proto/gRPC build container"},{"location":"reference/gen-doc/","text":"Generate Documentation \u00b6","title":"Introduction"},{"location":"reference/gen-doc/#generate-documentation","text":"","title":"Generate Documentation"},{"location":"reference/hello.pb/","text":"gRPC API Reference \u00b6 Contents \u00b6 Services HelloGreeter HelloIdentity Messages HelloGreeterSayHelloRequest HelloGreeterSayHelloResponse HelloIdentityVersionRequest HelloIdentityVersionResponse HelloVersion Scalar Value Types HelloGreeter \u00b6 The greeting service definition. SayHello \u00b6 rpc SayHello( HelloGreeterSayHelloRequest ) HelloGreeterSayHelloResponse Sends a greeting HelloIdentity \u00b6 Version \u00b6 rpc Version( HelloIdentityVersionRequest ) HelloIdentityVersionResponse Messages \u00b6 HelloGreeterSayHelloRequest \u00b6 The request message containing the user's name. Field Type Description name string none HelloGreeterSayHelloResponse \u00b6 The response message containing the greetings Field Type Description message string none HelloIdentityVersionRequest \u00b6 Empty request HelloIdentityVersionResponse \u00b6 Defines the response to version Field Type Description hello_version HelloVersion Hello application version HelloVersion \u00b6 Hello version in Major.Minor.Patch format. The goal of this message is to provide clients a method to determine the server and client versions. Field Type Description major int32 Version major number minor int32 Version minor number patch int32 Version patch number version string String representation of the version. Must be in major.minor.patch format. Enums \u00b6 HelloVersion.Version \u00b6 These values are constants that can be used by the client and server applications Name Number Description MUST_HAVE_ZERO_VALUE 0 Must be set in the proto file; ignore. MAJOR 0 Version major value of this specification MINOR 0 Version minor value of this specification PATCH 1 Version patch value of this specification Scalar Value Types \u00b6 .proto Type Notes C++ Type Java Type Python Type double double double float float float float float int32 Uses variable-length encoding. Inefficient for encoding negative numbers \u2013 if your field is likely to have negative values, use sint32 instead. int32 int int int64 Uses variable-length encoding. Inefficient for encoding negative numbers \u2013 if your field is likely to have negative values, use sint64 instead. int64 long int/long uint32 Uses variable-length encoding. uint32 int int/long uint64 Uses variable-length encoding. uint64 long int/long sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long sfixed32 Always four bytes. int32 int int sfixed64 Always eight bytes. int64 long int/long bool bool boolean boolean string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode bytes May contain any arbitrary sequence of bytes. string ByteString str","title":"Example Generated documentation"},{"location":"reference/hello.pb/#grpc-api-reference","text":"","title":"gRPC API Reference"},{"location":"reference/hello.pb/#contents","text":"Services HelloGreeter HelloIdentity Messages HelloGreeterSayHelloRequest HelloGreeterSayHelloResponse HelloIdentityVersionRequest HelloIdentityVersionResponse HelloVersion Scalar Value Types","title":"Contents"},{"location":"reference/hello.pb/#servicehellohellogreeter","text":"The greeting service definition.","title":"HelloGreeter"},{"location":"reference/hello.pb/#methodhellohellogreetersayhello","text":"rpc SayHello( HelloGreeterSayHelloRequest ) HelloGreeterSayHelloResponse Sends a greeting","title":"SayHello"},{"location":"reference/hello.pb/#servicehellohelloidentity","text":"","title":"HelloIdentity"},{"location":"reference/hello.pb/#methodhellohelloidentityversion","text":"rpc Version( HelloIdentityVersionRequest ) HelloIdentityVersionResponse","title":"Version"},{"location":"reference/hello.pb/#messages","text":"","title":"Messages"},{"location":"reference/hello.pb/#hellogreetersayhellorequest","text":"The request message containing the user's name. Field Type Description name string none","title":"HelloGreeterSayHelloRequest"},{"location":"reference/hello.pb/#hellogreetersayhelloresponse","text":"The response message containing the greetings Field Type Description message string none","title":"HelloGreeterSayHelloResponse"},{"location":"reference/hello.pb/#helloidentityversionrequest","text":"Empty request","title":"HelloIdentityVersionRequest"},{"location":"reference/hello.pb/#helloidentityversionresponse","text":"Defines the response to version Field Type Description hello_version HelloVersion Hello application version","title":"HelloIdentityVersionResponse"},{"location":"reference/hello.pb/#helloversion","text":"Hello version in Major.Minor.Patch format. The goal of this message is to provide clients a method to determine the server and client versions. Field Type Description major int32 Version major number minor int32 Version minor number patch int32 Version patch number version string String representation of the version. Must be in major.minor.patch format.","title":"HelloVersion"},{"location":"reference/hello.pb/#enums","text":"","title":"Enums"},{"location":"reference/hello.pb/#helloversionversion","text":"These values are constants that can be used by the client and server applications Name Number Description MUST_HAVE_ZERO_VALUE 0 Must be set in the proto file; ignore. MAJOR 0 Version major value of this specification MINOR 0 Version minor value of this specification PATCH 1 Version patch value of this specification","title":"HelloVersion.Version"},{"location":"reference/hello.pb/#scalar-value-types","text":".proto Type Notes C++ Type Java Type Python Type","title":"Scalar Value Types"},{"location":"reference/intro/","text":"Reference \u00b6","title":"Introduction"},{"location":"reference/intro/#reference","text":"","title":"Reference"},{"location":"reference/rate-limiter/","text":"Rate Limiter \u00b6","title":"Rate Limiter"},{"location":"reference/rate-limiter/#rate-limiter","text":"","title":"Rate Limiter"},{"location":"reference/rest/","text":"REST \u00b6","title":"REST"},{"location":"reference/rest/#rest","text":"","title":"REST"},{"location":"reference/style-guide/","text":"Protocol Buffer Style Guide \u00b6 Please first read Google's Protocol Buffer Style Guide : Quote This document provides a style guide for .proto files. By following these conventions, you'll make your protocol buffer message definitions and their corresponding classes consistent and easy to read. Note that protocol buffer style has evolved over time, so it is likely that you will see .proto files written in different conventions or styles. Please respect the existing style when you modify these files. Consistency is key. However, it is best to adopt the current best style when you are creating a new .proto file. The following documentation is provided as a set of guidelines to help you in your gRPC APIs. Types \u00b6 string types should be used only for ids, messages, or opaque values. They are not meant to marshal information as a yaml . Instead create a concrete message . Only use map for opaque values like labels, key-value pairs, etc. Do not use them for operations. Use enums instead. Value options should not be passed as string . Instead of passing \"Done\", or \"paused\", use enums for these value, making it clear to the reader. Try not to use uint64 . Instead try to use signed int64 . (See CSI #172 ) Services \u00b6 See CSI as an example. Use Camelcase Services should be in the format AppName . Note that the service is a collection of APIs and are grouped as such in the documentation. Here is an example for OpenStorageVolume RPCs \u00b6 All APIs should have a single message for the request and a single message for the response with the following style: [App]Request|Response See CSI as an example. RPCs will be created as methods to the service object , therefore there is no need to add the service name as part of the RPC. For example, use Foo , or Bar instead or ServiceFoo or ServiceBar as RPC names. Enums \u00b6 Follow the Google protobuf style for enums According to the Google guide, the enum of zero value should be labeled as UNSPECIFIED to check if it was not set since 0 is the default value set when the client does not provide it. Wrap enums in messages so that their string values are clearer. Wrapping an enum in a message also has the benefit of not needing to prefix the enums with namespaced information. For example, instead of using the enum XATTR_UNSPECIFIED , the example above uses just UNSPECIFIED since it is inide the Xattr message. The generated code will be namepaced: Proto: // Xattr defines implementation specific volume attribute message Xattr { enum Value { // Value is uninitialized or unknown UNSPECIFIED = 0; // Enable on-demand copy-on-write on the volume COW_ON_DEMAND = 1; } } Using the enum in a Proto message VolumeSpec { // Holds the extended attributes for the volume Xattr.Value xattr = 1; } Notice the namepaced and string values in the generated output code: type Xattr_Value int32 const ( // Value is uninitialized or unknown Xattr_UNSPECIFIED Xattr_Value = 0 // Enable on-demand copy-on-write on the volume Xattr_COW_ON_DEMAND Xattr_Value = 1 ) var Xattr_Value_name = map[int32]string{ 0: \"UNSPECIFIED\", 1: \"COW_ON_DEMAND\", } var Xattr_Value_value = map[string]int32{ \"UNSPECIFIED\": 0, \"COW_ON_DEMAND\": 1, } typedef VolueSpec struct { // Holds the extended attributes for the volume Xattr Xattr_Value `protobuf:\"varint,36,opt,name=xattr,enum=openstorage.api.Xattr_Value\" json:\"xattr,omitempty\"` } Messages \u00b6 If at all possible, APIs must be supported forever once released. They will almost never be deprecated since at some point you may have many versions of the clients. So please be clear and careful on the API you create. If we need to change or update, you can always add values. Field Numbers \u00b6 If it is a new message, start with the field number of 1 . If it is an addition to a message, continue the field number sequence by one. If you are using oneof you may want to start with a large value for the field number so that they do not interfere with other values in the message: string s3_storage_class = 7; // Start at field number 200 to allow for expansion oneof credential_type { // Credentials for AWS/S3 SdkAwsCredentialRequest aws_credential = 200; // Credentials for Azure SdkAzureCredentialRequest azure_credential = 201; // Credentials for Google SdkGoogleCredentialRequest google_credential = 202; } Deprecation \u00b6 Here is the process if you would like to deprecate: According to proto3 Language Guide set the value in the message to deprecated and add a (deprecated) string to the comment as follows: // (deprecated) Field documentation here int32 field = 6 [deprecated = true]; Comment in the a changelog that the value is deprecated. Provide at least two releases before removing support for that value in the message. Make sure to document in the release notes of the product the deprecation. Once at least two releases have passed. Reserve the field number as shown in the proto3 Language Guide : message Foo { reserved 6; } It is essential that no values override the field number when updating or replacing. From Google's guide: Warning If you update a message type by entirely removing a field, or commenting it out, future users can reuse the field number when making their own updates to the type. This can cause severe issues if they later load old versions of the same .proto, including data corruption, privacy bugs, and so on. REST \u00b6 REST endpoints are autogenerated from the protofile by the grpc-gateway protoc compiler. All APIs should add the appropriate information to generate a REST endpoint for their service. Here is an example: rpc Inspect(RoleInspectRequest) returns (RoleInspectResponse){ option(google.api.http) = { get: \"/v1/roles/{name}\" }; } // Delete an existing role rpc Delete(RoleDeleteRequest) returns (RoleDeleteResponse){ option(google.api.http) = { delete: \"/v1/roles/{name}\" }; } // Update an existing role rpc Update(RoleUpdateRequest) returns (RoleUpdateResponse){ option(google.api.http) = { put: \"/v1/roles\" body: \"*\" }; } Here are the guidelines for REST commands: Endpoint must be prefixed as follows: /v1///{any variables if needed} . Use the appropriate HTTP method. Here are some guidelines: For Create RPCs use the post http method For Inspect and List RPCs use the get http method For Update RPCs use the put http method For Delete RPCs use the delete http method Use get for immutable calls. Use put with body: \"*\" most calls that need to send a message to the SDK server. Please see grpc-gateway documentation for more information. Documentation \u00b6 All APIs, messages, and types should be documented if possible. The grpc-framework utilizes protoc-gen-doc to automatically generate documentation from your protocol buffers file. Documenting Messages Document each value of the message. Do not use Golang style. Do not repeat the name of the variable in Golang Camel Format in the comment to document it since the variable could be in other styles in other languages. For example: // Provides volume's exclusive bytes and its total usage. This cannot be // retrieved individually and is obtained as part node's usage for a given // node. message VolumeUsage { // id for the volume/snapshot string volume_id = 1; // name of the volume/snapshot string volume_name = 2; // uuid of the pool that this volume belongs to string pool_uuid = 3; // size in bytes exclusively used by the volume/snapshot uint64 exclusive_bytes = 4; // size in bytes by the volume/snapshot uint64 total_bytes = 5; // set to true if this volume is snapshot created by cloudbackups bool local_cloud_snapshot = 6; } Here is an example: \u00b6 Protocol buffers file: hello.proto Documentation in markdown format: hello.pb.md","title":"Style Guide"},{"location":"reference/style-guide/#protocol-buffer-style-guide","text":"Please first read Google's Protocol Buffer Style Guide : Quote This document provides a style guide for .proto files. By following these conventions, you'll make your protocol buffer message definitions and their corresponding classes consistent and easy to read. Note that protocol buffer style has evolved over time, so it is likely that you will see .proto files written in different conventions or styles. Please respect the existing style when you modify these files. Consistency is key. However, it is best to adopt the current best style when you are creating a new .proto file. The following documentation is provided as a set of guidelines to help you in your gRPC APIs.","title":"Protocol Buffer Style Guide"},{"location":"reference/style-guide/#types","text":"string types should be used only for ids, messages, or opaque values. They are not meant to marshal information as a yaml . Instead create a concrete message . Only use map for opaque values like labels, key-value pairs, etc. Do not use them for operations. Use enums instead. Value options should not be passed as string . Instead of passing \"Done\", or \"paused\", use enums for these value, making it clear to the reader. Try not to use uint64 . Instead try to use signed int64 . (See CSI #172 )","title":"Types"},{"location":"reference/style-guide/#services","text":"See CSI as an example. Use Camelcase Services should be in the format AppName . Note that the service is a collection of APIs and are grouped as such in the documentation. Here is an example for OpenStorageVolume","title":"Services"},{"location":"reference/style-guide/#rpcs","text":"All APIs should have a single message for the request and a single message for the response with the following style: [App]Request|Response See CSI as an example. RPCs will be created as methods to the service object , therefore there is no need to add the service name as part of the RPC. For example, use Foo , or Bar instead or ServiceFoo or ServiceBar as RPC names.","title":"RPCs"},{"location":"reference/style-guide/#enums","text":"Follow the Google protobuf style for enums According to the Google guide, the enum of zero value should be labeled as UNSPECIFIED to check if it was not set since 0 is the default value set when the client does not provide it. Wrap enums in messages so that their string values are clearer. Wrapping an enum in a message also has the benefit of not needing to prefix the enums with namespaced information. For example, instead of using the enum XATTR_UNSPECIFIED , the example above uses just UNSPECIFIED since it is inide the Xattr message. The generated code will be namepaced: Proto: // Xattr defines implementation specific volume attribute message Xattr { enum Value { // Value is uninitialized or unknown UNSPECIFIED = 0; // Enable on-demand copy-on-write on the volume COW_ON_DEMAND = 1; } } Using the enum in a Proto message VolumeSpec { // Holds the extended attributes for the volume Xattr.Value xattr = 1; } Notice the namepaced and string values in the generated output code: type Xattr_Value int32 const ( // Value is uninitialized or unknown Xattr_UNSPECIFIED Xattr_Value = 0 // Enable on-demand copy-on-write on the volume Xattr_COW_ON_DEMAND Xattr_Value = 1 ) var Xattr_Value_name = map[int32]string{ 0: \"UNSPECIFIED\", 1: \"COW_ON_DEMAND\", } var Xattr_Value_value = map[string]int32{ \"UNSPECIFIED\": 0, \"COW_ON_DEMAND\": 1, } typedef VolueSpec struct { // Holds the extended attributes for the volume Xattr Xattr_Value `protobuf:\"varint,36,opt,name=xattr,enum=openstorage.api.Xattr_Value\" json:\"xattr,omitempty\"` }","title":"Enums"},{"location":"reference/style-guide/#messages","text":"If at all possible, APIs must be supported forever once released. They will almost never be deprecated since at some point you may have many versions of the clients. So please be clear and careful on the API you create. If we need to change or update, you can always add values.","title":"Messages"},{"location":"reference/style-guide/#field-numbers","text":"If it is a new message, start with the field number of 1 . If it is an addition to a message, continue the field number sequence by one. If you are using oneof you may want to start with a large value for the field number so that they do not interfere with other values in the message: string s3_storage_class = 7; // Start at field number 200 to allow for expansion oneof credential_type { // Credentials for AWS/S3 SdkAwsCredentialRequest aws_credential = 200; // Credentials for Azure SdkAzureCredentialRequest azure_credential = 201; // Credentials for Google SdkGoogleCredentialRequest google_credential = 202; }","title":"Field Numbers"},{"location":"reference/style-guide/#deprecation","text":"Here is the process if you would like to deprecate: According to proto3 Language Guide set the value in the message to deprecated and add a (deprecated) string to the comment as follows: // (deprecated) Field documentation here int32 field = 6 [deprecated = true]; Comment in the a changelog that the value is deprecated. Provide at least two releases before removing support for that value in the message. Make sure to document in the release notes of the product the deprecation. Once at least two releases have passed. Reserve the field number as shown in the proto3 Language Guide : message Foo { reserved 6; } It is essential that no values override the field number when updating or replacing. From Google's guide: Warning If you update a message type by entirely removing a field, or commenting it out, future users can reuse the field number when making their own updates to the type. This can cause severe issues if they later load old versions of the same .proto, including data corruption, privacy bugs, and so on.","title":"Deprecation"},{"location":"reference/style-guide/#rest","text":"REST endpoints are autogenerated from the protofile by the grpc-gateway protoc compiler. All APIs should add the appropriate information to generate a REST endpoint for their service. Here is an example: rpc Inspect(RoleInspectRequest) returns (RoleInspectResponse){ option(google.api.http) = { get: \"/v1/roles/{name}\" }; } // Delete an existing role rpc Delete(RoleDeleteRequest) returns (RoleDeleteResponse){ option(google.api.http) = { delete: \"/v1/roles/{name}\" }; } // Update an existing role rpc Update(RoleUpdateRequest) returns (RoleUpdateResponse){ option(google.api.http) = { put: \"/v1/roles\" body: \"*\" }; } Here are the guidelines for REST commands: Endpoint must be prefixed as follows: /v1///{any variables if needed} . Use the appropriate HTTP method. Here are some guidelines: For Create RPCs use the post http method For Inspect and List RPCs use the get http method For Update RPCs use the put http method For Delete RPCs use the delete http method Use get for immutable calls. Use put with body: \"*\" most calls that need to send a message to the SDK server. Please see grpc-gateway documentation for more information.","title":"REST"},{"location":"reference/style-guide/#documentation","text":"All APIs, messages, and types should be documented if possible. The grpc-framework utilizes protoc-gen-doc to automatically generate documentation from your protocol buffers file. Documenting Messages Document each value of the message. Do not use Golang style. Do not repeat the name of the variable in Golang Camel Format in the comment to document it since the variable could be in other styles in other languages. For example: // Provides volume's exclusive bytes and its total usage. This cannot be // retrieved individually and is obtained as part node's usage for a given // node. message VolumeUsage { // id for the volume/snapshot string volume_id = 1; // name of the volume/snapshot string volume_name = 2; // uuid of the pool that this volume belongs to string pool_uuid = 3; // size in bytes exclusively used by the volume/snapshot uint64 exclusive_bytes = 4; // size in bytes by the volume/snapshot uint64 total_bytes = 5; // set to true if this volume is snapshot created by cloudbackups bool local_cloud_snapshot = 6; }","title":"Documentation"},{"location":"reference/style-guide/#here-is-an-example","text":"Protocol buffers file: hello.proto Documentation in markdown format: hello.pb.md","title":"Here is an example:"},{"location":"reference/security/audit/","text":"Audit \u00b6","title":"Audit"},{"location":"reference/security/audit/#audit","text":"","title":"Audit"},{"location":"reference/security/authentication/","text":"Authentication \u00b6","title":"Authentication"},{"location":"reference/security/authentication/#authentication","text":"","title":"Authentication"},{"location":"reference/security/authorization/","text":"Authorization \u00b6","title":"Authorization"},{"location":"reference/security/authorization/#authorization","text":"","title":"Authorization"},{"location":"reference/security/intro/","text":"Security \u00b6","title":"Security"},{"location":"reference/security/intro/#security","text":"","title":"Security"},{"location":"reference/security/tls/","text":"TLS \u00b6","title":"TLS"},{"location":"reference/security/tls/#tls","text":"","title":"TLS"},{"location":"tutorial/client/","text":"Tutorial: gRPC Client \u00b6","title":"Tutorial: gRPC Client"},{"location":"tutorial/client/#tutorial-grpc-client","text":"","title":"Tutorial: gRPC Client"},{"location":"tutorial/intro/","text":"Tutorial \u00b6 This tutorial will guide you to create your sample application on your system. You will need Docker (or complient runtime) and Go installed Container Runtime \u00b6 Linux \u00b6 First, make sure to have a container runtime installed like Docker or podman . MacOS \u00b6 If you use a MacOS system, then it is recommended to use Docker Desktop . Windows \u00b6 If you use Windows, it is highly recommended to install WSL and Docker Desktop . Sample Application \u00b6 Open a command prompt and make a new directory: mkdir hello cd hello Populate with the sample application from the grpc-framework: curl -L \\ https://github.com/libopenstorage/grpc-framework/archive/refs/heads/master.tar.gz | \\ tar xz --strip=3 \"grpc-framework-master/test/app\" Run go mod init . See Golang: Getting Started for more information: go mod init hello Now add the grpc-framework as a dependency: go get github.com/libopenstorage/grpc-framework@v0.0.8 Let golang determine the rest of the dependencies: go mod tidy Build: make Run the server: ./bin/server On another terminal run the client: ./bin/client","title":"Introduction"},{"location":"tutorial/intro/#tutorial","text":"This tutorial will guide you to create your sample application on your system. You will need Docker (or complient runtime) and Go installed","title":"Tutorial"},{"location":"tutorial/intro/#container-runtime","text":"","title":"Container Runtime"},{"location":"tutorial/intro/#linux","text":"First, make sure to have a container runtime installed like Docker or podman .","title":"Linux"},{"location":"tutorial/intro/#macos","text":"If you use a MacOS system, then it is recommended to use Docker Desktop .","title":"MacOS"},{"location":"tutorial/intro/#windows","text":"If you use Windows, it is highly recommended to install WSL and Docker Desktop .","title":"Windows"},{"location":"tutorial/intro/#sample-application","text":"Open a command prompt and make a new directory: mkdir hello cd hello Populate with the sample application from the grpc-framework: curl -L \\ https://github.com/libopenstorage/grpc-framework/archive/refs/heads/master.tar.gz | \\ tar xz --strip=3 \"grpc-framework-master/test/app\" Run go mod init . See Golang: Getting Started for more information: go mod init hello Now add the grpc-framework as a dependency: go get github.com/libopenstorage/grpc-framework@v0.0.8 Let golang determine the rest of the dependencies: go mod tidy Build: make Run the server: ./bin/server On another terminal run the client: ./bin/client","title":"Sample Application"},{"location":"tutorial/proto/","text":"Proto \u00b6","title":"Proto"},{"location":"tutorial/proto/#proto","text":"","title":"Proto"},{"location":"tutorial/rate-limit/","text":"Rate limit \u00b6","title":"Rate limit"},{"location":"tutorial/rate-limit/#rate-limit","text":"","title":"Rate limit"},{"location":"tutorial/rest/","text":"REST \u00b6","title":"REST"},{"location":"tutorial/rest/#rest","text":"","title":"REST"},{"location":"tutorial/server/","text":"Creating the gRPC Server \u00b6","title":"Creating the gRPC Server"},{"location":"tutorial/server/#creating-the-grpc-server","text":"","title":"Creating the gRPC Server"},{"location":"tutorial/security/authentication/","text":"Authentication \u00b6","title":"Authentication"},{"location":"tutorial/security/authentication/#authentication","text":"","title":"Authentication"},{"location":"tutorial/security/ownership/","text":"Ownership \u00b6","title":"Ownership"},{"location":"tutorial/security/ownership/#ownership","text":"","title":"Ownership"},{"location":"tutorial/security/rbac/","text":"RBAC \u00b6","title":"RBAC"},{"location":"tutorial/security/rbac/#rbac","text":"","title":"RBAC"},{"location":"tutorial/security/tls/","text":"","title":"Tls"}]}
\ No newline at end of file
+{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Welcome to grpc-framework \u00b6 The grpc-framework enables Golang developers to create secure gRPC applications easily. The project provides developers with the following features: Generate REST and swagger APIs Generate Markdown documentation Security Authentication (OIDC and JWT supported) Authorization (RBAC / Role Based Access Control) TLS support Auditing Rate Limiter Metrics for Prometheus API Logging proto/gRPC build container And more... Usage \u00b6 To add the library to your Golang application use the following command: go get github.com/libopenstorage/grpc-framework@v0.1.0 Also, use the following container version on your builds: quay.io/openstorage/grpc-framework:v0.1.0 Here is an example: PROTO_FILE = ./api/hello.proto proto: docker run \\ --privileged --rm \\ -v $(shell pwd):/go/src/code \\ -e \"GOPATH=/go\" \\ -e \"DOCKER_PROTO=yes\" \\ -e \"PROTO_USER=$(shell id -u)\" \\ -e \"PROTO_GROUP=$(shell id -g)\" \\ -e \"PATH=/bin:/usr/bin:/usr/local/bin:/go/bin:/usr/local/go/bin\" \\ quay.io/openstorage/grpc-framework:v0.1.0 \\ make docker-proto docker-proto: ifndef DOCKER_PROTO $(error Do not run directly. Run 'make proto' instead.) endif grpcfw $(PROTO_FILE) grpcfw-rest $(PROTO_FILE) grpcfw-doc $(PROTO_FILE) We are working on a tutorial, but in the meantime, please check out the example test program . Projects Used \u00b6 grpc-framework uses the following excellent projects in the framework: gRPC Golang gRPC REST Gateway Golang JWT Logging with logrus Generate Markdown documentation","title":"Home"},{"location":"#welcome-to-grpc-framework","text":"The grpc-framework enables Golang developers to create secure gRPC applications easily. The project provides developers with the following features: Generate REST and swagger APIs Generate Markdown documentation Security Authentication (OIDC and JWT supported) Authorization (RBAC / Role Based Access Control) TLS support Auditing Rate Limiter Metrics for Prometheus API Logging proto/gRPC build container And more...","title":"Welcome to grpc-framework"},{"location":"#usage","text":"To add the library to your Golang application use the following command: go get github.com/libopenstorage/grpc-framework@v0.1.0 Also, use the following container version on your builds: quay.io/openstorage/grpc-framework:v0.1.0 Here is an example: PROTO_FILE = ./api/hello.proto proto: docker run \\ --privileged --rm \\ -v $(shell pwd):/go/src/code \\ -e \"GOPATH=/go\" \\ -e \"DOCKER_PROTO=yes\" \\ -e \"PROTO_USER=$(shell id -u)\" \\ -e \"PROTO_GROUP=$(shell id -g)\" \\ -e \"PATH=/bin:/usr/bin:/usr/local/bin:/go/bin:/usr/local/go/bin\" \\ quay.io/openstorage/grpc-framework:v0.1.0 \\ make docker-proto docker-proto: ifndef DOCKER_PROTO $(error Do not run directly. Run 'make proto' instead.) endif grpcfw $(PROTO_FILE) grpcfw-rest $(PROTO_FILE) grpcfw-doc $(PROTO_FILE) We are working on a tutorial, but in the meantime, please check out the example test program .","title":"Usage"},{"location":"#projects-used","text":"grpc-framework uses the following excellent projects in the framework: gRPC Golang gRPC REST Gateway Golang JWT Logging with logrus Generate Markdown documentation","title":"Projects Used"},{"location":"about/","text":"About \u00b6 The software was first created for our OpenStorage project, but we then decided to make it its own separate framework so that other projects can use it easily. See also: KubeCon 2019 San Diego / Securing Your Services with Authentication, Authorization, and RBAC in gRPC","title":"About"},{"location":"about/#about","text":"The software was first created for our OpenStorage project, but we then decided to make it its own separate framework so that other projects can use it easily. See also: KubeCon 2019 San Diego / Securing Your Services with Authentication, Authorization, and RBAC in gRPC","title":"About"},{"location":"intro/","text":"Introduction \u00b6 The following will guide through some of the features provided by this framework Containerize tools \u00b6 The framework provides the latest tools for generating gRPC as a single container called quay.io/openstorage/grpc-framework . Here is a sample set of targets for a Makefile on how the container can be used to generate gRPC code from your protocol buffer files. PROTO_FILE = ./api/hello.proto proto: docker run \\ --privileged --rm \\ -v $(shell pwd):/go/src/code \\ -e \"GOPATH=/go\" \\ -e \"DOCKER_PROTO=yes\" \\ -e \"PROTO_USER=$(shell id -u)\" \\ -e \"PROTO_GROUP=$(shell id -g)\" \\ -e \"PATH=/bin:/usr/bin:/usr/local/bin:/go/bin:/usr/local/go/bin\" \\ quay.io/openstorage/grpc-framework:v0.1.0 \\ make docker-proto docker-proto: ifndef DOCKER_PROTO $(error Do not run directly. Run 'make proto' instead.) endif grpcfw $(PROTO_FILE) grpcfw-rest $(PROTO_FILE) grpcfw-doc $(PROTO_FILE) The framework provides a set of grpcfw* programs in a container, to help with the generation of the sources from the protocol buffers file. Generate REST and swagger APIs \u00b6 The framework utilizes the grpc-gateway to generate a REST interface for your application. The framework will setup and start the HTTP server and automatically connect it to your gRPC server. The REST APIs will be served by the HTTP server which are then forwared to the gRPC server to be handled. The framework will also generate a swagger API file which can be provided to REST client developers. The following is an example of how a gRPC service can be used from a REST client. // The greeting service definition. service HelloGreeter { // Sends a greeting rpc SayHello (HelloGreeterSayHelloRequest) returns (HelloGreeterSayHelloResponse) { option(google.api.http) = { post: \"/v1/greeter/sayhello\" body: \"*\" }; } } // The request message containing the user's name. message HelloGreeterSayHelloRequest { string name = 1; } // The response message containing the greetings message HelloGreeterSayHelloResponse { string message = 1; } Here, the grpc-gateway would use the information located in the option(google.api.http) section of your gRPC rpc to generate a REST call. To enable the REST server for your application, you would need to enable it in your configuration: import( \"github.com/libopenstorage/grpc-framework/server\" ) ... grpcConfig := &server.ServerConfig{ Name: \"hello\", Address: \"127.0.0.1:9009\", Socket: \"/tmp/hello-server.sock\", AuditOutput: os.Stdout, AccessOutput: os.Stdout, } restPort := \"9010\" grpcConfig.WithDefaultRestServer(restPort) ... Once the server is started, you can then use a REST client to send commands to your application: $ curl -X POST -d '{ \"name\": \"Luis\" }' \\ --silent http://localhost:9010/v1/greeter/sayhello | jq { \"message\": \"Hello, Luis\" } Generate Markdown documentation \u00b6 The framework also provides protoc-doc to generate Markdown documentation from the comments on your protocol buffers files. Security \u00b6 The framework makes it simple to add authentication, authorization, and TLS to secure your application. Authentication and RBAC authorization are provided by a set of interceptors in the gRPC server. Authentication (OIDC and JWT supported) \u00b6 The framework support shared secret, public-private key, or OpenID Connect authentication models. Authorization \u00b6 The framework provides (RBAC) role based access control for gRPC services as well as a generic resource authorization model. TLS support \u00b6 The framework provides TLS server support. Auditing \u00b6 The framework logs access to the APIs by recording identifying information read from the authentication token of the caller. This is done by an interceptor that is automatically installed by the framework when authentication is enabled on the gRPC server. Rate Limiter \u00b6 The framework provides rate limiter support with a plan for future releases tor provide the rate limit per user. Metrics for Prometheus \u00b6 Support for Prometheus is provided by go-grpc-prometheus . API Logging \u00b6 Like auditing, a logging interceptor is provided which can provide rountrip information for API services. proto/gRPC build container \u00b6 All tools and updated libraries are all provided by a container to make it simple to utilize on your projects.","title":"Introduction"},{"location":"intro/#introduction","text":"The following will guide through some of the features provided by this framework","title":"Introduction"},{"location":"intro/#containerize-tools","text":"The framework provides the latest tools for generating gRPC as a single container called quay.io/openstorage/grpc-framework . Here is a sample set of targets for a Makefile on how the container can be used to generate gRPC code from your protocol buffer files. PROTO_FILE = ./api/hello.proto proto: docker run \\ --privileged --rm \\ -v $(shell pwd):/go/src/code \\ -e \"GOPATH=/go\" \\ -e \"DOCKER_PROTO=yes\" \\ -e \"PROTO_USER=$(shell id -u)\" \\ -e \"PROTO_GROUP=$(shell id -g)\" \\ -e \"PATH=/bin:/usr/bin:/usr/local/bin:/go/bin:/usr/local/go/bin\" \\ quay.io/openstorage/grpc-framework:v0.1.0 \\ make docker-proto docker-proto: ifndef DOCKER_PROTO $(error Do not run directly. Run 'make proto' instead.) endif grpcfw $(PROTO_FILE) grpcfw-rest $(PROTO_FILE) grpcfw-doc $(PROTO_FILE) The framework provides a set of grpcfw* programs in a container, to help with the generation of the sources from the protocol buffers file.","title":"Containerize tools"},{"location":"intro/#generate-rest-and-swagger-apis","text":"The framework utilizes the grpc-gateway to generate a REST interface for your application. The framework will setup and start the HTTP server and automatically connect it to your gRPC server. The REST APIs will be served by the HTTP server which are then forwared to the gRPC server to be handled. The framework will also generate a swagger API file which can be provided to REST client developers. The following is an example of how a gRPC service can be used from a REST client. // The greeting service definition. service HelloGreeter { // Sends a greeting rpc SayHello (HelloGreeterSayHelloRequest) returns (HelloGreeterSayHelloResponse) { option(google.api.http) = { post: \"/v1/greeter/sayhello\" body: \"*\" }; } } // The request message containing the user's name. message HelloGreeterSayHelloRequest { string name = 1; } // The response message containing the greetings message HelloGreeterSayHelloResponse { string message = 1; } Here, the grpc-gateway would use the information located in the option(google.api.http) section of your gRPC rpc to generate a REST call. To enable the REST server for your application, you would need to enable it in your configuration: import( \"github.com/libopenstorage/grpc-framework/server\" ) ... grpcConfig := &server.ServerConfig{ Name: \"hello\", Address: \"127.0.0.1:9009\", Socket: \"/tmp/hello-server.sock\", AuditOutput: os.Stdout, AccessOutput: os.Stdout, } restPort := \"9010\" grpcConfig.WithDefaultRestServer(restPort) ... Once the server is started, you can then use a REST client to send commands to your application: $ curl -X POST -d '{ \"name\": \"Luis\" }' \\ --silent http://localhost:9010/v1/greeter/sayhello | jq { \"message\": \"Hello, Luis\" }","title":"Generate REST and swagger APIs"},{"location":"intro/#generate-markdown-documentation","text":"The framework also provides protoc-doc to generate Markdown documentation from the comments on your protocol buffers files.","title":"Generate Markdown documentation"},{"location":"intro/#security","text":"The framework makes it simple to add authentication, authorization, and TLS to secure your application. Authentication and RBAC authorization are provided by a set of interceptors in the gRPC server.","title":"Security"},{"location":"intro/#authentication-oidc-and-jwt-supported","text":"The framework support shared secret, public-private key, or OpenID Connect authentication models.","title":"Authentication (OIDC and JWT supported)"},{"location":"intro/#authorization","text":"The framework provides (RBAC) role based access control for gRPC services as well as a generic resource authorization model.","title":"Authorization"},{"location":"intro/#tls-support","text":"The framework provides TLS server support.","title":"TLS support"},{"location":"intro/#auditing","text":"The framework logs access to the APIs by recording identifying information read from the authentication token of the caller. This is done by an interceptor that is automatically installed by the framework when authentication is enabled on the gRPC server.","title":"Auditing"},{"location":"intro/#rate-limiter","text":"The framework provides rate limiter support with a plan for future releases tor provide the rate limit per user.","title":"Rate Limiter"},{"location":"intro/#metrics-for-prometheus","text":"Support for Prometheus is provided by go-grpc-prometheus .","title":"Metrics for Prometheus"},{"location":"intro/#api-logging","text":"Like auditing, a logging interceptor is provided which can provide rountrip information for API services.","title":"API Logging"},{"location":"intro/#protogrpc-build-container","text":"All tools and updated libraries are all provided by a container to make it simple to utilize on your projects.","title":"proto/gRPC build container"},{"location":"reference/gen-doc/","text":"Generate Documentation \u00b6","title":"Introduction"},{"location":"reference/gen-doc/#generate-documentation","text":"","title":"Generate Documentation"},{"location":"reference/hello.pb/","text":"gRPC API Reference \u00b6 Contents \u00b6 Services HelloGreeter HelloIdentity Messages HelloGreeterSayHelloRequest HelloGreeterSayHelloResponse HelloIdentityVersionRequest HelloIdentityVersionResponse HelloVersion Scalar Value Types HelloGreeter \u00b6 The greeting service definition. SayHello \u00b6 rpc SayHello( HelloGreeterSayHelloRequest ) HelloGreeterSayHelloResponse Sends a greeting HelloIdentity \u00b6 Version \u00b6 rpc Version( HelloIdentityVersionRequest ) HelloIdentityVersionResponse Messages \u00b6 HelloGreeterSayHelloRequest \u00b6 The request message containing the user's name. Field Type Description name string none HelloGreeterSayHelloResponse \u00b6 The response message containing the greetings Field Type Description message string none HelloIdentityVersionRequest \u00b6 Empty request HelloIdentityVersionResponse \u00b6 Defines the response to version Field Type Description hello_version HelloVersion Hello application version HelloVersion \u00b6 Hello version in Major.Minor.Patch format. The goal of this message is to provide clients a method to determine the server and client versions. Field Type Description major int32 Version major number minor int32 Version minor number patch int32 Version patch number version string String representation of the version. Must be in major.minor.patch format. Enums \u00b6 HelloVersion.Version \u00b6 These values are constants that can be used by the client and server applications Name Number Description MUST_HAVE_ZERO_VALUE 0 Must be set in the proto file; ignore. MAJOR 0 Version major value of this specification MINOR 0 Version minor value of this specification PATCH 1 Version patch value of this specification Scalar Value Types \u00b6 .proto Type Notes C++ Type Java Type Python Type double double double float float float float float int32 Uses variable-length encoding. Inefficient for encoding negative numbers \u2013 if your field is likely to have negative values, use sint32 instead. int32 int int int64 Uses variable-length encoding. Inefficient for encoding negative numbers \u2013 if your field is likely to have negative values, use sint64 instead. int64 long int/long uint32 Uses variable-length encoding. uint32 int int/long uint64 Uses variable-length encoding. uint64 long int/long sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long sfixed32 Always four bytes. int32 int int sfixed64 Always eight bytes. int64 long int/long bool bool boolean boolean string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode bytes May contain any arbitrary sequence of bytes. string ByteString str","title":"Example Generated documentation"},{"location":"reference/hello.pb/#grpc-api-reference","text":"","title":"gRPC API Reference"},{"location":"reference/hello.pb/#contents","text":"Services HelloGreeter HelloIdentity Messages HelloGreeterSayHelloRequest HelloGreeterSayHelloResponse HelloIdentityVersionRequest HelloIdentityVersionResponse HelloVersion Scalar Value Types","title":"Contents"},{"location":"reference/hello.pb/#servicehellohellogreeter","text":"The greeting service definition.","title":"HelloGreeter"},{"location":"reference/hello.pb/#methodhellohellogreetersayhello","text":"rpc SayHello( HelloGreeterSayHelloRequest ) HelloGreeterSayHelloResponse Sends a greeting","title":"SayHello"},{"location":"reference/hello.pb/#servicehellohelloidentity","text":"","title":"HelloIdentity"},{"location":"reference/hello.pb/#methodhellohelloidentityversion","text":"rpc Version( HelloIdentityVersionRequest ) HelloIdentityVersionResponse","title":"Version"},{"location":"reference/hello.pb/#messages","text":"","title":"Messages"},{"location":"reference/hello.pb/#hellogreetersayhellorequest","text":"The request message containing the user's name. Field Type Description name string none","title":"HelloGreeterSayHelloRequest"},{"location":"reference/hello.pb/#hellogreetersayhelloresponse","text":"The response message containing the greetings Field Type Description message string none","title":"HelloGreeterSayHelloResponse"},{"location":"reference/hello.pb/#helloidentityversionrequest","text":"Empty request","title":"HelloIdentityVersionRequest"},{"location":"reference/hello.pb/#helloidentityversionresponse","text":"Defines the response to version Field Type Description hello_version HelloVersion Hello application version","title":"HelloIdentityVersionResponse"},{"location":"reference/hello.pb/#helloversion","text":"Hello version in Major.Minor.Patch format. The goal of this message is to provide clients a method to determine the server and client versions. Field Type Description major int32 Version major number minor int32 Version minor number patch int32 Version patch number version string String representation of the version. Must be in major.minor.patch format.","title":"HelloVersion"},{"location":"reference/hello.pb/#enums","text":"","title":"Enums"},{"location":"reference/hello.pb/#helloversionversion","text":"These values are constants that can be used by the client and server applications Name Number Description MUST_HAVE_ZERO_VALUE 0 Must be set in the proto file; ignore. MAJOR 0 Version major value of this specification MINOR 0 Version minor value of this specification PATCH 1 Version patch value of this specification","title":"HelloVersion.Version"},{"location":"reference/hello.pb/#scalar-value-types","text":".proto Type Notes C++ Type Java Type Python Type","title":"Scalar Value Types"},{"location":"reference/intro/","text":"Reference \u00b6","title":"Introduction"},{"location":"reference/intro/#reference","text":"","title":"Reference"},{"location":"reference/rate-limiter/","text":"Rate Limiter \u00b6","title":"Rate Limiter"},{"location":"reference/rate-limiter/#rate-limiter","text":"","title":"Rate Limiter"},{"location":"reference/rest/","text":"REST \u00b6","title":"REST"},{"location":"reference/rest/#rest","text":"","title":"REST"},{"location":"reference/style-guide/","text":"Protocol Buffer Style Guide \u00b6 Please first read Google's Protocol Buffer Style Guide : Quote This document provides a style guide for .proto files. By following these conventions, you'll make your protocol buffer message definitions and their corresponding classes consistent and easy to read. Note that protocol buffer style has evolved over time, so it is likely that you will see .proto files written in different conventions or styles. Please respect the existing style when you modify these files. Consistency is key. However, it is best to adopt the current best style when you are creating a new .proto file. The following documentation is provided as a set of guidelines to help you in your gRPC APIs. Types \u00b6 string types should be used only for ids, messages, or opaque values. They are not meant to marshal information as a yaml . Instead create a concrete message . Only use map for opaque values like labels, key-value pairs, etc. Do not use them for operations. Use enums instead. Value options should not be passed as string . Instead of passing \"Done\", or \"paused\", use enums for these value, making it clear to the reader. Try not to use uint64 . Instead try to use signed int64 . (See CSI #172 ) Services \u00b6 See CSI as an example. Use Camelcase Services should be in the format AppName . Note that the service is a collection of APIs and are grouped as such in the documentation. Here is an example for OpenStorageVolume RPCs \u00b6 All APIs should have a single message for the request and a single message for the response with the following style: [App]Request|Response See CSI as an example. RPCs will be created as methods to the service object , therefore there is no need to add the service name as part of the RPC. For example, use Foo , or Bar instead or ServiceFoo or ServiceBar as RPC names. Enums \u00b6 Follow the Google protobuf style for enums According to the Google guide, the enum of zero value should be labeled as UNSPECIFIED to check if it was not set since 0 is the default value set when the client does not provide it. Wrap enums in messages so that their string values are clearer. Wrapping an enum in a message also has the benefit of not needing to prefix the enums with namespaced information. For example, instead of using the enum XATTR_UNSPECIFIED , the example above uses just UNSPECIFIED since it is inide the Xattr message. The generated code will be namepaced: Proto: // Xattr defines implementation specific volume attribute message Xattr { enum Value { // Value is uninitialized or unknown UNSPECIFIED = 0; // Enable on-demand copy-on-write on the volume COW_ON_DEMAND = 1; } } Using the enum in a Proto message VolumeSpec { // Holds the extended attributes for the volume Xattr.Value xattr = 1; } Notice the namepaced and string values in the generated output code: type Xattr_Value int32 const ( // Value is uninitialized or unknown Xattr_UNSPECIFIED Xattr_Value = 0 // Enable on-demand copy-on-write on the volume Xattr_COW_ON_DEMAND Xattr_Value = 1 ) var Xattr_Value_name = map[int32]string{ 0: \"UNSPECIFIED\", 1: \"COW_ON_DEMAND\", } var Xattr_Value_value = map[string]int32{ \"UNSPECIFIED\": 0, \"COW_ON_DEMAND\": 1, } typedef VolueSpec struct { // Holds the extended attributes for the volume Xattr Xattr_Value `protobuf:\"varint,36,opt,name=xattr,enum=openstorage.api.Xattr_Value\" json:\"xattr,omitempty\"` } Messages \u00b6 If at all possible, APIs must be supported forever once released. They will almost never be deprecated since at some point you may have many versions of the clients. So please be clear and careful on the API you create. If we need to change or update, you can always add values. Field Numbers \u00b6 If it is a new message, start with the field number of 1 . If it is an addition to a message, continue the field number sequence by one. If you are using oneof you may want to start with a large value for the field number so that they do not interfere with other values in the message: string s3_storage_class = 7; // Start at field number 200 to allow for expansion oneof credential_type { // Credentials for AWS/S3 SdkAwsCredentialRequest aws_credential = 200; // Credentials for Azure SdkAzureCredentialRequest azure_credential = 201; // Credentials for Google SdkGoogleCredentialRequest google_credential = 202; } Deprecation \u00b6 Here is the process if you would like to deprecate: According to proto3 Language Guide set the value in the message to deprecated and add a (deprecated) string to the comment as follows: // (deprecated) Field documentation here int32 field = 6 [deprecated = true]; Comment in the a changelog that the value is deprecated. Provide at least two releases before removing support for that value in the message. Make sure to document in the release notes of the product the deprecation. Once at least two releases have passed. Reserve the field number as shown in the proto3 Language Guide : message Foo { reserved 6; } It is essential that no values override the field number when updating or replacing. From Google's guide: Warning If you update a message type by entirely removing a field, or commenting it out, future users can reuse the field number when making their own updates to the type. This can cause severe issues if they later load old versions of the same .proto, including data corruption, privacy bugs, and so on. REST \u00b6 REST endpoints are autogenerated from the protofile by the grpc-gateway protoc compiler. All APIs should add the appropriate information to generate a REST endpoint for their service. Here is an example: rpc Inspect(RoleInspectRequest) returns (RoleInspectResponse){ option(google.api.http) = { get: \"/v1/roles/{name}\" }; } // Delete an existing role rpc Delete(RoleDeleteRequest) returns (RoleDeleteResponse){ option(google.api.http) = { delete: \"/v1/roles/{name}\" }; } // Update an existing role rpc Update(RoleUpdateRequest) returns (RoleUpdateResponse){ option(google.api.http) = { put: \"/v1/roles\" body: \"*\" }; } Here are the guidelines for REST commands: Endpoint must be prefixed as follows: /v1///{any variables if needed} . Use the appropriate HTTP method. Here are some guidelines: For Create RPCs use the post http method For Inspect and List RPCs use the get http method For Update RPCs use the put http method For Delete RPCs use the delete http method Use get for immutable calls. Use put with body: \"*\" most calls that need to send a message to the SDK server. Please see grpc-gateway documentation for more information. Documentation \u00b6 All APIs, messages, and types should be documented if possible. The grpc-framework utilizes protoc-gen-doc to automatically generate documentation from your protocol buffers file. Documenting Messages Document each value of the message. Do not use Golang style. Do not repeat the name of the variable in Golang Camel Format in the comment to document it since the variable could be in other styles in other languages. For example: // Provides volume's exclusive bytes and its total usage. This cannot be // retrieved individually and is obtained as part node's usage for a given // node. message VolumeUsage { // id for the volume/snapshot string volume_id = 1; // name of the volume/snapshot string volume_name = 2; // uuid of the pool that this volume belongs to string pool_uuid = 3; // size in bytes exclusively used by the volume/snapshot uint64 exclusive_bytes = 4; // size in bytes by the volume/snapshot uint64 total_bytes = 5; // set to true if this volume is snapshot created by cloudbackups bool local_cloud_snapshot = 6; } Here is an example: \u00b6 Protocol buffers file: hello.proto Documentation in markdown format: hello.pb.md","title":"Style Guide"},{"location":"reference/style-guide/#protocol-buffer-style-guide","text":"Please first read Google's Protocol Buffer Style Guide : Quote This document provides a style guide for .proto files. By following these conventions, you'll make your protocol buffer message definitions and their corresponding classes consistent and easy to read. Note that protocol buffer style has evolved over time, so it is likely that you will see .proto files written in different conventions or styles. Please respect the existing style when you modify these files. Consistency is key. However, it is best to adopt the current best style when you are creating a new .proto file. The following documentation is provided as a set of guidelines to help you in your gRPC APIs.","title":"Protocol Buffer Style Guide"},{"location":"reference/style-guide/#types","text":"string types should be used only for ids, messages, or opaque values. They are not meant to marshal information as a yaml . Instead create a concrete message . Only use map for opaque values like labels, key-value pairs, etc. Do not use them for operations. Use enums instead. Value options should not be passed as string . Instead of passing \"Done\", or \"paused\", use enums for these value, making it clear to the reader. Try not to use uint64 . Instead try to use signed int64 . (See CSI #172 )","title":"Types"},{"location":"reference/style-guide/#services","text":"See CSI as an example. Use Camelcase Services should be in the format AppName . Note that the service is a collection of APIs and are grouped as such in the documentation. Here is an example for OpenStorageVolume","title":"Services"},{"location":"reference/style-guide/#rpcs","text":"All APIs should have a single message for the request and a single message for the response with the following style: [App]Request|Response See CSI as an example. RPCs will be created as methods to the service object , therefore there is no need to add the service name as part of the RPC. For example, use Foo , or Bar instead or ServiceFoo or ServiceBar as RPC names.","title":"RPCs"},{"location":"reference/style-guide/#enums","text":"Follow the Google protobuf style for enums According to the Google guide, the enum of zero value should be labeled as UNSPECIFIED to check if it was not set since 0 is the default value set when the client does not provide it. Wrap enums in messages so that their string values are clearer. Wrapping an enum in a message also has the benefit of not needing to prefix the enums with namespaced information. For example, instead of using the enum XATTR_UNSPECIFIED , the example above uses just UNSPECIFIED since it is inide the Xattr message. The generated code will be namepaced: Proto: // Xattr defines implementation specific volume attribute message Xattr { enum Value { // Value is uninitialized or unknown UNSPECIFIED = 0; // Enable on-demand copy-on-write on the volume COW_ON_DEMAND = 1; } } Using the enum in a Proto message VolumeSpec { // Holds the extended attributes for the volume Xattr.Value xattr = 1; } Notice the namepaced and string values in the generated output code: type Xattr_Value int32 const ( // Value is uninitialized or unknown Xattr_UNSPECIFIED Xattr_Value = 0 // Enable on-demand copy-on-write on the volume Xattr_COW_ON_DEMAND Xattr_Value = 1 ) var Xattr_Value_name = map[int32]string{ 0: \"UNSPECIFIED\", 1: \"COW_ON_DEMAND\", } var Xattr_Value_value = map[string]int32{ \"UNSPECIFIED\": 0, \"COW_ON_DEMAND\": 1, } typedef VolueSpec struct { // Holds the extended attributes for the volume Xattr Xattr_Value `protobuf:\"varint,36,opt,name=xattr,enum=openstorage.api.Xattr_Value\" json:\"xattr,omitempty\"` }","title":"Enums"},{"location":"reference/style-guide/#messages","text":"If at all possible, APIs must be supported forever once released. They will almost never be deprecated since at some point you may have many versions of the clients. So please be clear and careful on the API you create. If we need to change or update, you can always add values.","title":"Messages"},{"location":"reference/style-guide/#field-numbers","text":"If it is a new message, start with the field number of 1 . If it is an addition to a message, continue the field number sequence by one. If you are using oneof you may want to start with a large value for the field number so that they do not interfere with other values in the message: string s3_storage_class = 7; // Start at field number 200 to allow for expansion oneof credential_type { // Credentials for AWS/S3 SdkAwsCredentialRequest aws_credential = 200; // Credentials for Azure SdkAzureCredentialRequest azure_credential = 201; // Credentials for Google SdkGoogleCredentialRequest google_credential = 202; }","title":"Field Numbers"},{"location":"reference/style-guide/#deprecation","text":"Here is the process if you would like to deprecate: According to proto3 Language Guide set the value in the message to deprecated and add a (deprecated) string to the comment as follows: // (deprecated) Field documentation here int32 field = 6 [deprecated = true]; Comment in the a changelog that the value is deprecated. Provide at least two releases before removing support for that value in the message. Make sure to document in the release notes of the product the deprecation. Once at least two releases have passed. Reserve the field number as shown in the proto3 Language Guide : message Foo { reserved 6; } It is essential that no values override the field number when updating or replacing. From Google's guide: Warning If you update a message type by entirely removing a field, or commenting it out, future users can reuse the field number when making their own updates to the type. This can cause severe issues if they later load old versions of the same .proto, including data corruption, privacy bugs, and so on.","title":"Deprecation"},{"location":"reference/style-guide/#rest","text":"REST endpoints are autogenerated from the protofile by the grpc-gateway protoc compiler. All APIs should add the appropriate information to generate a REST endpoint for their service. Here is an example: rpc Inspect(RoleInspectRequest) returns (RoleInspectResponse){ option(google.api.http) = { get: \"/v1/roles/{name}\" }; } // Delete an existing role rpc Delete(RoleDeleteRequest) returns (RoleDeleteResponse){ option(google.api.http) = { delete: \"/v1/roles/{name}\" }; } // Update an existing role rpc Update(RoleUpdateRequest) returns (RoleUpdateResponse){ option(google.api.http) = { put: \"/v1/roles\" body: \"*\" }; } Here are the guidelines for REST commands: Endpoint must be prefixed as follows: /v1///{any variables if needed} . Use the appropriate HTTP method. Here are some guidelines: For Create RPCs use the post http method For Inspect and List RPCs use the get http method For Update RPCs use the put http method For Delete RPCs use the delete http method Use get for immutable calls. Use put with body: \"*\" most calls that need to send a message to the SDK server. Please see grpc-gateway documentation for more information.","title":"REST"},{"location":"reference/style-guide/#documentation","text":"All APIs, messages, and types should be documented if possible. The grpc-framework utilizes protoc-gen-doc to automatically generate documentation from your protocol buffers file. Documenting Messages Document each value of the message. Do not use Golang style. Do not repeat the name of the variable in Golang Camel Format in the comment to document it since the variable could be in other styles in other languages. For example: // Provides volume's exclusive bytes and its total usage. This cannot be // retrieved individually and is obtained as part node's usage for a given // node. message VolumeUsage { // id for the volume/snapshot string volume_id = 1; // name of the volume/snapshot string volume_name = 2; // uuid of the pool that this volume belongs to string pool_uuid = 3; // size in bytes exclusively used by the volume/snapshot uint64 exclusive_bytes = 4; // size in bytes by the volume/snapshot uint64 total_bytes = 5; // set to true if this volume is snapshot created by cloudbackups bool local_cloud_snapshot = 6; }","title":"Documentation"},{"location":"reference/style-guide/#here-is-an-example","text":"Protocol buffers file: hello.proto Documentation in markdown format: hello.pb.md","title":"Here is an example:"},{"location":"reference/security/audit/","text":"Audit \u00b6","title":"Audit"},{"location":"reference/security/audit/#audit","text":"","title":"Audit"},{"location":"reference/security/authentication/","text":"Authentication \u00b6","title":"Authentication"},{"location":"reference/security/authentication/#authentication","text":"","title":"Authentication"},{"location":"reference/security/authorization/","text":"Authorization \u00b6","title":"Authorization"},{"location":"reference/security/authorization/#authorization","text":"","title":"Authorization"},{"location":"reference/security/intro/","text":"Security \u00b6","title":"Security"},{"location":"reference/security/intro/#security","text":"","title":"Security"},{"location":"reference/security/tls/","text":"TLS \u00b6","title":"TLS"},{"location":"reference/security/tls/#tls","text":"","title":"TLS"},{"location":"tutorial/client/","text":"Tutorial: gRPC Client \u00b6","title":"Tutorial: gRPC Client"},{"location":"tutorial/client/#tutorial-grpc-client","text":"","title":"Tutorial: gRPC Client"},{"location":"tutorial/intro/","text":"Tutorial \u00b6 This tutorial will guide you to create your sample application on your system. You will need Docker (or complient runtime) and Go installed Container Runtime \u00b6 Linux \u00b6 First, make sure to have a container runtime installed like Docker or podman . MacOS \u00b6 If you use a MacOS system, then it is recommended to use Docker Desktop . Windows \u00b6 If you use Windows, it is highly recommended to install WSL and Docker Desktop . Sample Application \u00b6 Open a command prompt and make a new directory: mkdir hello cd hello Populate with the sample application from the grpc-framework: curl -L \\ https://github.com/libopenstorage/grpc-framework/archive/refs/heads/master.tar.gz | \\ tar xz --strip=3 \"grpc-framework-master/test/app\" Run go mod init . See Golang: Getting Started for more information: go mod init hello Now add the grpc-framework as a dependency: go get github.com/libopenstorage/grpc-framework@v0.0.8 Let golang determine the rest of the dependencies: go mod tidy Build: make Run the server: ./bin/server On another terminal run the client: ./bin/client","title":"Introduction"},{"location":"tutorial/intro/#tutorial","text":"This tutorial will guide you to create your sample application on your system. You will need Docker (or complient runtime) and Go installed","title":"Tutorial"},{"location":"tutorial/intro/#container-runtime","text":"","title":"Container Runtime"},{"location":"tutorial/intro/#linux","text":"First, make sure to have a container runtime installed like Docker or podman .","title":"Linux"},{"location":"tutorial/intro/#macos","text":"If you use a MacOS system, then it is recommended to use Docker Desktop .","title":"MacOS"},{"location":"tutorial/intro/#windows","text":"If you use Windows, it is highly recommended to install WSL and Docker Desktop .","title":"Windows"},{"location":"tutorial/intro/#sample-application","text":"Open a command prompt and make a new directory: mkdir hello cd hello Populate with the sample application from the grpc-framework: curl -L \\ https://github.com/libopenstorage/grpc-framework/archive/refs/heads/master.tar.gz | \\ tar xz --strip=3 \"grpc-framework-master/test/app\" Run go mod init . See Golang: Getting Started for more information: go mod init hello Now add the grpc-framework as a dependency: go get github.com/libopenstorage/grpc-framework@v0.0.8 Let golang determine the rest of the dependencies: go mod tidy Build: make Run the server: ./bin/server On another terminal run the client: ./bin/client","title":"Sample Application"},{"location":"tutorial/proto/","text":"Proto \u00b6","title":"Proto"},{"location":"tutorial/proto/#proto","text":"","title":"Proto"},{"location":"tutorial/rate-limit/","text":"Rate limit \u00b6","title":"Rate limit"},{"location":"tutorial/rate-limit/#rate-limit","text":"","title":"Rate limit"},{"location":"tutorial/rest/","text":"REST \u00b6","title":"REST"},{"location":"tutorial/rest/#rest","text":"","title":"REST"},{"location":"tutorial/server/","text":"Creating the gRPC Server \u00b6","title":"Creating the gRPC Server"},{"location":"tutorial/server/#creating-the-grpc-server","text":"","title":"Creating the gRPC Server"},{"location":"tutorial/security/authentication/","text":"Authentication \u00b6","title":"Authentication"},{"location":"tutorial/security/authentication/#authentication","text":"","title":"Authentication"},{"location":"tutorial/security/ownership/","text":"Ownership \u00b6","title":"Ownership"},{"location":"tutorial/security/ownership/#ownership","text":"","title":"Ownership"},{"location":"tutorial/security/rbac/","text":"RBAC \u00b6","title":"RBAC"},{"location":"tutorial/security/rbac/#rbac","text":"","title":"RBAC"},{"location":"tutorial/security/tls/","text":"","title":"Tls"}]}
\ No newline at end of file
diff --git a/docs/sitemap.xml b/docs/sitemap.xml
index f5ea9b9..0f8724e 100644
--- a/docs/sitemap.xml
+++ b/docs/sitemap.xml
@@ -1,123 +1,3 @@
-
- None
- 2023-07-22
- daily
-
-
- None
- 2023-07-22
- daily
-
-
- None
- 2023-07-22
- daily
-
-
- None
- 2023-07-22
- daily
-
-
- None
- 2023-07-22
- daily
-
-
- None
- 2023-07-22
- daily
-
-
- None
- 2023-07-22
- daily
-
-
- None
- 2023-07-22
- daily
-
-
- None
- 2023-07-22
- daily
-
-
- None
- 2023-07-22
- daily
-
-
- None
- 2023-07-22
- daily
-
-
- None
- 2023-07-22
- daily
-
-
- None
- 2023-07-22
- daily
-
-
- None
- 2023-07-22
- daily
-
-
- None
- 2023-07-22
- daily
-
-
- None
- 2023-07-22
- daily
-
-
- None
- 2023-07-22
- daily
-
-
- None
- 2023-07-22
- daily
-
-
- None
- 2023-07-22
- daily
-
-
- None
- 2023-07-22
- daily
-
-
- None
- 2023-07-22
- daily
-
-
- None
- 2023-07-22
- daily
-
-
- None
- 2023-07-22
- daily
-
-
- None
- 2023-07-22
- daily
-
\ No newline at end of file
diff --git a/docs/sitemap.xml.gz b/docs/sitemap.xml.gz
index a7904bd..20f07a3 100644
Binary files a/docs/sitemap.xml.gz and b/docs/sitemap.xml.gz differ
diff --git a/docs/tutorial/intro/index.html b/docs/tutorial/intro/index.html
index 09bba86..8fccbd7 100644
--- a/docs/tutorial/intro/index.html
+++ b/docs/tutorial/intro/index.html
@@ -9,7 +9,7 @@
-
+
diff --git a/docs/tutorial/proto/index.html b/docs/tutorial/proto/index.html
index b001bd5..4162194 100644
--- a/docs/tutorial/proto/index.html
+++ b/docs/tutorial/proto/index.html
@@ -9,7 +9,7 @@
-
+
diff --git a/docs/tutorial/rate-limit/index.html b/docs/tutorial/rate-limit/index.html
index 19a96d3..2fbef73 100644
--- a/docs/tutorial/rate-limit/index.html
+++ b/docs/tutorial/rate-limit/index.html
@@ -9,7 +9,7 @@
-
+
diff --git a/docs/tutorial/rest/index.html b/docs/tutorial/rest/index.html
index 72b4ac3..1228aac 100644
--- a/docs/tutorial/rest/index.html
+++ b/docs/tutorial/rest/index.html
@@ -9,7 +9,7 @@
-
+
diff --git a/docs/tutorial/security/authentication/index.html b/docs/tutorial/security/authentication/index.html
index 93d4de1..48042d7 100644
--- a/docs/tutorial/security/authentication/index.html
+++ b/docs/tutorial/security/authentication/index.html
@@ -9,7 +9,7 @@
-
+
diff --git a/docs/tutorial/security/ownership/index.html b/docs/tutorial/security/ownership/index.html
index c5bc903..05b8452 100644
--- a/docs/tutorial/security/ownership/index.html
+++ b/docs/tutorial/security/ownership/index.html
@@ -9,7 +9,7 @@
-
+
diff --git a/docs/tutorial/security/rbac/index.html b/docs/tutorial/security/rbac/index.html
index 7b7577d..80af23b 100644
--- a/docs/tutorial/security/rbac/index.html
+++ b/docs/tutorial/security/rbac/index.html
@@ -9,7 +9,7 @@
-
+
diff --git a/docs/tutorial/security/tls/index.html b/docs/tutorial/security/tls/index.html
index b1d67a5..2731e86 100644
--- a/docs/tutorial/security/tls/index.html
+++ b/docs/tutorial/security/tls/index.html
@@ -9,7 +9,7 @@
-
+
diff --git a/docs/tutorial/server/index.html b/docs/tutorial/server/index.html
index d812f56..1da0a73 100644
--- a/docs/tutorial/server/index.html
+++ b/docs/tutorial/server/index.html
@@ -9,7 +9,7 @@
-
+
diff --git a/requirements.txt b/requirements.txt
index cc3c959..0ac7f23 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -12,7 +12,6 @@ mkdocs==1.4.3
mkdocs-material==8.5.11
mkdocs-material-extensions==1.1.1
packaging==22.0
-pkg_resources==0.0.0
pur==7.0.0
Pygments==2.13.0
pymdown-extensions==9.9
diff --git a/website/docs/index.md b/website/docs/index.md
index bce3a42..088bdfc 100644
--- a/website/docs/index.md
+++ b/website/docs/index.md
@@ -21,13 +21,13 @@ easily. The project provides developers with the following features:
To add the library to your Golang application use the following command:
```bash
-go get github.com/libopenstorage/grpc-framework@v0.0.8
+go get github.com/libopenstorage/grpc-framework@v0.1.0
```
Also, use the following container version on your builds:
```
-quay.io/openstorage/grpc-framework:v0.0.9
+quay.io/openstorage/grpc-framework:v0.1.0
```
Here is an example:
@@ -44,7 +44,7 @@ proto:
-e "PROTO_USER=$(shell id -u)" \
-e "PROTO_GROUP=$(shell id -g)" \
-e "PATH=/bin:/usr/bin:/usr/local/bin:/go/bin:/usr/local/go/bin" \
- quay.io/openstorage/grpc-framework:v0.0.9 \
+ quay.io/openstorage/grpc-framework:v0.1.0 \
make docker-proto
docker-proto:
diff --git a/website/docs/intro.md b/website/docs/intro.md
index 6538613..3681e01 100644
--- a/website/docs/intro.md
+++ b/website/docs/intro.md
@@ -21,7 +21,7 @@ proto:
-e "PROTO_USER=$(shell id -u)" \
-e "PROTO_GROUP=$(shell id -g)" \
-e "PATH=/bin:/usr/bin:/usr/local/bin:/go/bin:/usr/local/go/bin" \
- quay.io/openstorage/grpc-framework:latest \
+ quay.io/openstorage/grpc-framework:v0.1.0 \
make docker-proto
docker-proto: