{"id":23338507,"url":"https://github.com/cloudwan/goten-sdk","last_synced_at":"2025-08-01T17:37:42.060Z","repository":{"id":57654580,"uuid":"451565932","full_name":"cloudwan/goten-sdk","owner":"cloudwan","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-31T07:25:55.000Z","size":1012,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-07-31T11:13:21.816Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloudwan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-01-24T17:33:29.000Z","updated_at":"2025-07-31T07:25:58.000Z","dependencies_parsed_at":"2024-04-26T18:30:04.362Z","dependency_job_id":"615deead-a15d-454d-a035-d011b21db87e","html_url":"https://github.com/cloudwan/goten-sdk","commit_stats":null,"previous_names":[],"tags_count":164,"template":false,"template_full_name":null,"purl":"pkg:github/cloudwan/goten-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudwan%2Fgoten-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudwan%2Fgoten-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudwan%2Fgoten-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudwan%2Fgoten-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloudwan","download_url":"https://codeload.github.com/cloudwan/goten-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudwan%2Fgoten-sdk/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268044215,"owners_count":24186561,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-31T02:00:08.723Z","response_time":66,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-21T03:14:08.921Z","updated_at":"2025-08-01T17:37:42.034Z","avatar_url":"https://github.com/cloudwan.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Goten SDK\n\n## Overview\nGoten is a development framework for resource-oriented gRPC service. In a sense, it is an additional language built on\ntop of [gRPC](https://grpc.io/) and [Google Protocol Buffers](https://developers.google.com/protocol-buffers).\nIt provides more higher-level components like services, references, resources. It standardizes service description in\nproto files and provides dedicated [protoc compilers](https://grpc.io/docs/protoc-installation/) generating basic Golang\nclient/server code.\n\nGoten-based service is basically made of set of logically bound APIs and resources with additional REST\ntranscoding. Each resource, unless explicitly configured by service developer, has CRUD functionality automatically\ngenerated, with many extra features like watching (updates streaming), text based searching (optional, for selected resources),\nCAS (compare and swap).\nMore about conventions adopted in Goten: [Google API design](https://cloud.google.com/apis/design/),\n[basic CRUD](https://cloud.google.com/apis/design/standard_methods)\n\nWe can define following components:\n* Goten-based Service -\u003e This is the highest level object, which basically describes full service. It contains logically\n  bound set of resources and RPC APIs, forming together coherent and possibly minimalistic service, focusing on specific\n  business job.\n* Resource -\u003e This is basically protobuf message with resource annotation and name. It conforms to the standards defined in\n  Google API conventions. If you look at proto files in any Goten service, you should see that each resource has basically\n  two files: \u003cresource_name\u003e.proto and \u003cresource_name\u003e_change.proto. First one describes resource schema itself, second\n  describes \"change\" of a resource and is used in Watch requests (subscription for updates). Each resource also has its\n  own dedicated RPC API (of the same name) with CRUD functionality.\n* RPC API -\u003e Set of RPC methods. Most of them are dedicated for single resources and have CRUD functionality, but it may\n  not always be the case. Each API has \u003capi_name\u003e_service.proto file and, if it contains custom developer-defined methods,\n  \u003capi_name\u003e_custom.proto. \n\nAs said before, Goten provides dedicated protoc compilers producing service code in Go language for both client and server side.\nWhile auto-generated code forms the biggest part of a service (usually), it also references some common, non-generated parts.\nThis repository contains common, client-side components referenced by that auto generated code. Therefore, Goten SDK is not meant to be\nused directly by any final application. However, it is used by any public client-side library generated by Goten.\n\nGoten SDK contains also some common protobuf files used by services developed on it.\n\n## Components\nGoten SDK contains common functions/interfaces used by auto-generated Golang libraries + some common protobuf files.\n\n### Access (runtime/access)\nAccess is a module in Goten-based service containing higher level objects for client side code. As higher level, I mean\nit does not contain raw basic clients for making API calls, it is for components built on top of that. Currently, Access\nis used primarily for Watcher component. Watcher utilizes Watch request (like LIST, but with real time updates) and\nhandles boilerplate parts like reconnections, automatic recovery etc.\n\n### Api (runtime/api)\nThis is not exactly Api, because Goten SDK is not that. This component contains just common protobuf files used by\nGoten based services. You will need them if you want to generate library in your preferable programming language.\n\n### Common Goten message interfaces (runtime/goten)\nThis is primarily home for GotenMessage interface, which is implemented by every generated (by Goten compiler) protobuf\nmessage in Golang.\n\n### Object interfaces (runtime/object)\nWhile GotenMessage is a minimal interface used by any generated struct (for protobuf message), Goten also comes with additional\nprotoc compilers capable of enriching these structs with much more functionality. For each message, Goten can provide\ndedicated, type-safe FieldMask and FieldPath objects. This is non-standard functionality that is typically not available\nusing widely-known protoc compilers for Golang. This module contains all definitions that can be provided by those\nextra compilers.\n\n### Resource interfaces (runtime/resource)\nThis module contains many interfaces associated with Goten resource - Resource itself, name object, reference, filter,\ndescriptor and so on.\n\n### Validate interfaces (runtime/validate)\nOptional interfaces implemented by some goten-generated messages.\n\n## How to use\nAs it was said, Goten SDK contains only public, client-side components referenced by Goten based services and its not\nmeant for development on its own. However, there are common steps to follow if you are developing application talking\nto a Goten service, and you want to use its SDK.\n\nIf you are happy with developing in Golang, we recommend to simply use our Go libraries generated by dedicated Goten\ncompilers. We include Go library in each SDK. All you need to do, apart from having access to an API endpoint, is to\ninstall Go (platform specific - see https://golang.org/doc/install). Then, you need to include SDK for interested service\nin your list of dependencies (Each of our SDKs is a Go module too).\n\nHowever, we also provide proto files, which can be used to generate client libraries in practically any programming\nlanguage. Then, you have a couple of more things to do:\n1. You need to install protoc [protoc](https://developers.google.com/protocol-buffers/docs/overview). You need to install\n  it in version at least 3.6.1. You need to verify you have the most basic files like\n  [WellKnownTypes](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf). If you have installed \n  in /usr/local (for example), then check /usr/local/include/google/protobuf directory.\n2. You need also some extra protobuf files from google. We use certain files from [googleapis](https://github.com/googleapis/googleapis).\n3. When using protoc, you need to also include directory runtime/api (from this repository) as proto include path.\n4. You need to install protoc plugin for your language.\n5. With all proto files and protoc installed, you should be able to generate library in your language.\n\nVery simple example for Golang:\n```shell\nPROTOINCLUDE=~/workspace:/usr/local/include\nGOGENPATH=$GOPATH/src\n\nprotoc \\\n    -I \"${PROTOINCLUDE}\" \\\n    \"--go_out=:${GOGENPATH}\" \\\n    \"${SERVICEPATH}\"/proto/v1/*.proto\n```\nAssumptions:\n* I put all google proto files in /usr/local/include - both well knowns and from googleapis.\n* SERVICEPATH points to location of goten based service. It is located in ~/workspace in fact. Therefore, PROTOINCLUDE will work.\n\nPart \"go_out\" is for golang, however they are other plugins for different languages.\nAs a tip, generated files are put according to a parameters taken from proto files. For example, for Golang,\noutput directory is dictated by parameter provided to go_out plugin combined with go_package option. Open\nany proto file and you should see something like:\n```proto\nsyntax = \"proto3\";\n\n// ....\n// some lines here....\n// ....\n\noption go_package = \"github.com/cloudwan/goten-sdk/runtime/api/view\";\n```\n\nIn result, for this little example, output file will be located in $GOPATH/src/github.com/cloudwan/goten-sdk/runtime/api/view.\nIn some cases, you may want to create a symlink to your repository, if you want to commit generated files!\n\nOf course each service may impose additional requirements, but above are the common steps.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudwan%2Fgoten-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloudwan%2Fgoten-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudwan%2Fgoten-sdk/lists"}