Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/cloudwan/goten-sdk
https://github.com/cloudwan/goten-sdk
Last synced: 8 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/cloudwan/goten-sdk
- Owner: cloudwan
- License: apache-2.0
- Created: 2022-01-24T17:33:29.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2024-10-17T13:54:48.000Z (2 months ago)
- Last Synced: 2024-10-19T12:07:15.958Z (2 months ago)
- Language: Go
- Size: 547 KB
- Stars: 0
- Watchers: 11
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Goten SDK
## Overview
Goten is a development framework for resource-oriented gRPC service. In a sense, it is an additional language built on
top of [gRPC](https://grpc.io/) and [Google Protocol Buffers](https://developers.google.com/protocol-buffers).
It provides more higher-level components like services, references, resources. It standardizes service description in
proto files and provides dedicated [protoc compilers](https://grpc.io/docs/protoc-installation/) generating basic Golang
client/server code.Goten-based service is basically made of set of logically bound APIs and resources with additional REST
transcoding. Each resource, unless explicitly configured by service developer, has CRUD functionality automatically
generated, with many extra features like watching (updates streaming), text based searching (optional, for selected resources),
CAS (compare and swap).
More about conventions adopted in Goten: [Google API design](https://cloud.google.com/apis/design/),
[basic CRUD](https://cloud.google.com/apis/design/standard_methods)We can define following components:
* Goten-based Service -> This is the highest level object, which basically describes full service. It contains logically
bound set of resources and RPC APIs, forming together coherent and possibly minimalistic service, focusing on specific
business job.
* Resource -> This is basically protobuf message with resource annotation and name. It conforms to the standards defined in
Google API conventions. If you look at proto files in any Goten service, you should see that each resource has basically
two files: .proto and _change.proto. First one describes resource schema itself, second
describes "change" of a resource and is used in Watch requests (subscription for updates). Each resource also has its
own dedicated RPC API (of the same name) with CRUD functionality.
* RPC API -> Set of RPC methods. Most of them are dedicated for single resources and have CRUD functionality, but it may
not always be the case. Each API has _service.proto file and, if it contains custom developer-defined methods,
_custom.proto.As said before, Goten provides dedicated protoc compilers producing service code in Go language for both client and server side.
While auto-generated code forms the biggest part of a service (usually), it also references some common, non-generated parts.
This repository contains common, client-side components referenced by that auto generated code. Therefore, Goten SDK is not meant to be
used directly by any final application. However, it is used by any public client-side library generated by Goten.Goten SDK contains also some common protobuf files used by services developed on it.
## Components
Goten SDK contains common functions/interfaces used by auto-generated Golang libraries + some common protobuf files.### Access (runtime/access)
Access is a module in Goten-based service containing higher level objects for client side code. As higher level, I mean
it does not contain raw basic clients for making API calls, it is for components built on top of that. Currently, Access
is used primarily for Watcher component. Watcher utilizes Watch request (like LIST, but with real time updates) and
handles boilerplate parts like reconnections, automatic recovery etc.### Api (runtime/api)
This is not exactly Api, because Goten SDK is not that. This component contains just common protobuf files used by
Goten based services. You will need them if you want to generate library in your preferable programming language.### Common Goten message interfaces (runtime/goten)
This is primarily home for GotenMessage interface, which is implemented by every generated (by Goten compiler) protobuf
message in Golang.### Object interfaces (runtime/object)
While GotenMessage is a minimal interface used by any generated struct (for protobuf message), Goten also comes with additional
protoc compilers capable of enriching these structs with much more functionality. For each message, Goten can provide
dedicated, type-safe FieldMask and FieldPath objects. This is non-standard functionality that is typically not available
using widely-known protoc compilers for Golang. This module contains all definitions that can be provided by those
extra compilers.### Resource interfaces (runtime/resource)
This module contains many interfaces associated with Goten resource - Resource itself, name object, reference, filter,
descriptor and so on.### Validate interfaces (runtime/validate)
Optional interfaces implemented by some goten-generated messages.## How to use
As it was said, Goten SDK contains only public, client-side components referenced by Goten based services and its not
meant for development on its own. However, there are common steps to follow if you are developing application talking
to a Goten service, and you want to use its SDK.If you are happy with developing in Golang, we recommend to simply use our Go libraries generated by dedicated Goten
compilers. We include Go library in each SDK. All you need to do, apart from having access to an API endpoint, is to
install Go (platform specific - see https://golang.org/doc/install). Then, you need to include SDK for interested service
in your list of dependencies (Each of our SDKs is a Go module too).However, we also provide proto files, which can be used to generate client libraries in practically any programming
language. Then, you have a couple of more things to do:
1. You need to install protoc [protoc](https://developers.google.com/protocol-buffers/docs/overview). You need to install
it in version at least 3.6.1. You need to verify you have the most basic files like
[WellKnownTypes](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf). If you have installed
in /usr/local (for example), then check /usr/local/include/google/protobuf directory.
2. You need also some extra protobuf files from google. We use certain files from [googleapis](https://github.com/googleapis/googleapis).
3. When using protoc, you need to also include directory runtime/api (from this repository) as proto include path.
4. You need to install protoc plugin for your language.
5. With all proto files and protoc installed, you should be able to generate library in your language.Very simple example for Golang:
```shell
PROTOINCLUDE=~/workspace:/usr/local/include
GOGENPATH=$GOPATH/srcprotoc \
-I "${PROTOINCLUDE}" \
"--go_out=:${GOGENPATH}" \
"${SERVICEPATH}"/proto/v1/*.proto
```
Assumptions:
* I put all google proto files in /usr/local/include - both well knowns and from googleapis.
* SERVICEPATH points to location of goten based service. It is located in ~/workspace in fact. Therefore, PROTOINCLUDE will work.Part "go_out" is for golang, however they are other plugins for different languages.
As a tip, generated files are put according to a parameters taken from proto files. For example, for Golang,
output directory is dictated by parameter provided to go_out plugin combined with go_package option. Open
any proto file and you should see something like:
```proto
syntax = "proto3";// ....
// some lines here....
// ....option go_package = "github.com/cloudwan/goten-sdk/runtime/api/view";
```In result, for this little example, output file will be located in $GOPATH/src/github.com/cloudwan/goten-sdk/runtime/api/view.
In some cases, you may want to create a symlink to your repository, if you want to commit generated files!Of course each service may impose additional requirements, but above are the common steps.