diff --git a/.github/ISSUE_TEMPLATE/00-bug.md b/.github/ISSUE_TEMPLATE/00-bug.md new file mode 100644 index 0000000..4dc4849 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/00-bug.md @@ -0,0 +1,38 @@ +--- +name: Bugs +about: config, server, client, or anything else +title: "affected/package: " +--- + + + +### What version of tRPC-Go are you using? + + +### Does this issue reproduce with the latest release? + + + +### What operating system and processor architecture are you using (`go env`)? + +
go env Output
+$ go env
+
+
+ +### What did you do? + + + + +### What did you expect to see? + + + +### What did you see instead? \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/01-feature.md b/.github/ISSUE_TEMPLATE/01-feature.md new file mode 100644 index 0000000..1e53472 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/01-feature.md @@ -0,0 +1,33 @@ +--- +name: Features +about: config, server, client, or anything else +title: "affected/package: " +--- + + + +### Is your feature request related to a problem? + + + +### What is the solution you'd like? + + + +### What alternatives have you considered? + + + +### Could you provide additional context? + + diff --git a/.github/ISSUE_TEMPLATE/03-proposal.md b/.github/ISSUE_TEMPLATE/03-proposal.md new file mode 100644 index 0000000..23e5cc1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/03-proposal.md @@ -0,0 +1,11 @@ +--- +name: Proposals +about: New external API or other notable changes +title: "proposal: affected/package: " +labels: Proposal +--- + + diff --git a/.github/workflows/cla.yml b/.github/workflows/cla.yml new file mode 100644 index 0000000..de11c47 --- /dev/null +++ b/.github/workflows/cla.yml @@ -0,0 +1,31 @@ +name: "CLA Assistant" +on: + issue_comment: + types: [created] + pull_request_target: + types: [opened, closed, synchronize, reopened] + +# explicitly configure permissions, in case your GITHUB_TOKEN workflow permissions are set to read-only in repository settings +permissions: + actions: write + contents: write + pull-requests: write + statuses: write + +jobs: + CLAAssistant: + runs-on: ubuntu-latest + steps: + - name: "CLA Assistant" + if: (github.event.comment.body == 'recheck' || github.event.comment.body == 'I have read the CLA Document and I hereby sign the CLA') || github.event_name == 'pull_request_target' + uses: contributor-assistant/github-action@v2.3.1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + PERSONAL_ACCESS_TOKEN: ${{ secrets.CLA_DATABASE_ACCESS_TOKEN }} + with: + remote-organization-name: trpc-group + remote-repository-name: cla-database + path-to-signatures: 'signatures/${{ github.event.repository.name }}-${{ github.repository_id }}/cla.json' + path-to-document: 'https://github.com/trpc-group/cla-database/blob/main/Tencent-Contributor-License-Agreement.md' + # branch should not be protected + branch: 'main' \ No newline at end of file diff --git a/.github/workflows/prc.yml b/.github/workflows/prc.yml new file mode 100644 index 0000000..3451a35 --- /dev/null +++ b/.github/workflows/prc.yml @@ -0,0 +1,60 @@ +name: Pull Request Check +on: + pull_request: + push: + workflow_dispatch: +permissions: + contents: read + pull-requests: read # Use with `only-new-issues` option. +jobs: + build: + name: build + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: actions/setup-go@v4 + with: + go-version: 1.19 + - name: Build + run: go build -v ./... + - name: Test + run: go test -v -coverprofile=coverage.out ./... + - name: Upload coverage reports to Codecov + uses: codecov/codecov-action@v3 + with: + files: coverage.out + flags: unittests + env: + CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} + golangci: + name: lint + runs-on: ubuntu-latest + steps: + - uses: actions/setup-go@v4 + with: + go-version: 1.19 + - uses: actions/checkout@v3 + - name: golangci-lint + uses: golangci/golangci-lint-action@v3 + with: + version: latest + only-new-issues: true + skip-cache: true # To prevent occasional failure of this action. + typos: + name: typos + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - name: typos + uses: crate-ci/typos@master + go-apidiff: + if: github.event_name == 'pull_request' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + with: + fetch-depth: 0 + - uses: actions/setup-go@v4 + with: + go-version: 1.19 + - uses: joelanford/go-apidiff@main diff --git a/README.md b/README.md index 1c45e5b..06973b3 100644 --- a/README.md +++ b/README.md @@ -1,92 +1,106 @@ -# fbs - -一个用 Go 实现的 flatbuffers 解析器 - -[English version](./docs/README_en.md) - -## 快速上手 - -使用方法： - -1. 首先导入 `package fbs`： - -```go -import "trpc.group/trpc-go/fbs" -``` - -2. 然后传入要解析的 flatbuffers 文件列表，创建 `Parser` 并调用 `ParseFiles` - -```go -filenames := []string{ - "./file1.fbs", // 给出一系列需要解析的 flatbuffers 文件名 - "./file2.fbs", -} -p := fbs.NewParser() -fds, err := p.ParseFiles(filenames...) -fd1 := fds[0] // file1.fbs 的解析结果（描述符） -fd2 := fds[1] // file2.fbs 的解析结果（描述符） -``` - -通过 `fds` 即可访问到描述符，从而可以使用 flatbuffers 文件中定义的 rpc service 里各个 method 的名字、输入输出类型、是否为流式等信息，描述符定义见 `desc.go` - -其中每个文件的描述符 `SchemaDesc` 各字段如下： - -```go -// SchemaDesc 描述了一个完整的 flatbuffers 文件 -type SchemaDesc struct { - Schema *ast.SchemaNode // Schema 存储抽象语法树(AST)的根节点 - Name string // Name 存储 .fbs 文件的文件名，如 "./file1.fbs" - // Namespaces 存储该文件中遇到的所有 namespace，其作用类似于 protobuf 中的 package - // 不同之处在于 flatbuffers 允许一个文件中出现多次 namespace - // 不同 namespace 下定义的 table/struct 等类型拥有各自不同的 namespace - Namespaces []string - Root string // Root 存储 flatbuffers 文件中的 root_type 声明 - FileExt string // FileExt 存储 flatbuffers 文件中的 file_extension 声明 - FileIdent string // FileIdent 存储 flatbuffers 文件中的 file_identifier 声明 - Attrs []string // Attrs 存储 flatbuffers 文件中的 attribute 声明（可能有多个） - Includes []string // Includes 存储所有 include 语句中的文件名 - Dependencies []*SchemaDesc // Dependencies 存储所有 include 语句对应的解析出的描述符 - Tables []*TableDesc // Tables 存储所有的 table 描述符 - Structs []*StructDesc // Structs 存储所有的 struct 描述符 - Enums []*EnumDesc // Enums 存储所有的 enumeration 描述符 - Unions []*UnionDesc // Unions 存储所有的 union 描述符 - RPCs []*RPCDesc // RPCs 存储所有 rpc service 描述符 -} -``` - -通过访问这些字段，如 `RPCs`，就可以得到 flatbuffers 文件中定义的信息，从而完成一系列相关的工作（如 rpc 桩代码的生成） - -## 工程目录结构 - -``` -. -├── desc.go # 各种节点对应描述符的定义 -├── desc_test.go -├── doc.go -├── docs # 实现文档 -├── errors.go # 错误处理机制 -├── errors_test.go -├── fbsfiles # 存放用于测试的 .fbs 文件 -├── fbs.y # 根据 flatbuffers 的语法写成 -├── fbs.y.go # 由 fbs.y 生成, 用于将 token 流解析为抽象语法树 -├── go.mod -├── go.sum -├── internal -│ └── ast # 存放抽象语法树中各节点的定义以及构造方法 -├── lexer.go # 实现 lexer -├── lexer_test.go -├── linker.go # 实现 linker -├── linker_test.go -├── parse_result.go # 存放解析结果的定义 -├── parser.go # 实现 parser -├── parser_test.go -├── reader.go # 实现 reader -├── README.md -└── scope.go # 实现 scope -``` - -更多内容见 [实现细节](./docs/implementation_cn.md) - -## 应用实例 - -本项目为 trpc-go 提供了支持生成 flatbuffers 相关桩代码的功能 \ No newline at end of file +English | [中文](README.zh_CN.md) + +# fbs + +A parser for flatbuffers in Go. + +## Getting Started + +1. Import `package fbs`: + +```go +import "trpc.group/trpc-go/fbs" +``` + +2. Pass in the flatbuffers file list you want to parse. Create a `Parser` and call `ParseFiles`. + +```go +filenames := []string{ + "./file1.fbs", // Pass in a list of flatbuffers files. + "./file2.fbs", +} +p := fbs.NewParser() +fds, err := p.ParseFiles(filenames...) +fd1 := fds[0] // The parsed result(descriptor) of file1.fbs +fd2 := fds[1] // The parsed result(descriptor) of file2.fbs +``` + +You can access the resulting descriptors from `fbs` and get rich information about every method definition of rpc + services, e.g. method names, input/output type, client/server streaming, etc. + +The descriptor `SchemaDesc` for every file has the following fields: + +```go +// SchemaDesc describes a complete .fbs file. +type SchemaDesc struct { + // Schema stores the root node of the AST. + Schema *ast.SchemaNode + // Name stores the .fbs file name. + Name string + // Namespace of schema will change in the course of processing each decl, these will be stored + // in this slice. Decls of table/struct/enum/union will set their own namespaces to be the last + // namespace in this slice. + // See parseResult.createSchemaDescriptor. + Namespaces []string + // Root stores root_type declaration in flatbuffers file. + Root string + // FileExt stores file_extension declaration in flatbuffers file. + FileExt string + // FileIdent stores file_identifier declaration in flatbuffers file. + FileIdent string + // Attrs stores attributes definitions in flatbuffers file. + Attrs []string + // Includes stores all included file names. + Includes []string + // Dependencies stores all descriptors corresponding to included files. + Dependencies []*SchemaDesc + // Tables stores all table descriptors. + Tables []*TableDesc + // Structs stores all struct descriptors. + Structs []*StructDesc + // Enums stores all enum descriptors. + Enums []*EnumDesc + // Unions stores all union descriptors. + Unions []*UnionDesc + // RPCs stores all rpc service descriptors. + RPCs []*RPCDesc +} +``` + +Through accessing these fields such as `RPCs`, you can get information defined in flatbuffers to get related + work done(e.g. generate stub files for rpc services). + +## Project Structure + +``` +. +├── desc.go # Definitions of descriptors for all kinds of node. +├── desc_test.go +├── doc.go +├── docs # Documents of implementation. +├── errors.go # Error handling. +├── errors_test.go +├── fbsfiles # Places .fbs for testing. +├── fbs.y # Hand-written according to the grammar of flatbuffers. +├── fbs.y.go # Generated by fbs.y, used to parse token stream to AST. +├── go.mod +├── go.sum +├── internal +│ └── ast # Stores definitions and constructions of nodes in AST. +├── lexer.go # lexer implementation. +├── lexer_test.go +├── linker.go # linker implementation. +├── linker_test.go +├── parse_result.go # Definition for parsed result. +├── parser.go # parser implementation. +├── parser_test.go +├── reader.go # reader implementation. +├── README.md +└── scope.go # scope implementation. +``` + +Further information see [implementation details](/docs/implementation.md) + +## Used in Practice + +This project enables trpc-go to have flatbuffers support. diff --git a/README.zh_CN.md b/README.zh_CN.md new file mode 100644 index 0000000..3fc3cf7 --- /dev/null +++ b/README.zh_CN.md @@ -0,0 +1,92 @@ +[English](README.md) | 中文 + +# fbs + +一个用 Go 实现的 flatbuffers 解析器 + +## 快速上手 + +使用方法： + +1. 首先导入 `package fbs`： + +```go +import "trpc.group/trpc-go/fbs" +``` + +2. 然后传入要解析的 flatbuffers 文件列表，创建 `Parser` 并调用 `ParseFiles` + +```go +filenames := []string{ + "./file1.fbs", // 给出一系列需要解析的 flatbuffers 文件名 + "./file2.fbs", +} +p := fbs.NewParser() +fds, err := p.ParseFiles(filenames...) +fd1 := fds[0] // file1.fbs 的解析结果（描述符） +fd2 := fds[1] // file2.fbs 的解析结果（描述符） +``` + +通过 `fbs` 即可访问到描述符，从而可以使用 flatbuffers 文件中定义的 rpc service 里各个 method 的名字、输入输出类型、是否为流式等信息，描述符定义见 `desc.go` + +其中每个文件的描述符 `SchemaDesc` 各字段如下： + +```go +// SchemaDesc 描述了一个完整的 flatbuffers 文件 +type SchemaDesc struct { + Schema *ast.SchemaNode // Schema 存储抽象语法树(AST)的根节点 + Name string // Name 存储 .fbs 文件的文件名，如 "./file1.fbs" + // Namespaces 存储该文件中遇到的所有 namespace，其作用类似于 protobuf 中的 package + // 不同之处在于 flatbuffers 允许一个文件中出现多次 namespace + // 不同 namespace 下定义的 table/struct 等类型拥有各自不同的 namespace + Namespaces []string + Root string // Root 存储 flatbuffers 文件中的 root_type 声明 + FileExt string // FileExt 存储 flatbuffers 文件中的 file_extension 声明 + FileIdent string // FileIdent 存储 flatbuffers 文件中的 file_identifier 声明 + Attrs []string // Attrs 存储 flatbuffers 文件中的 attribute 声明（可能有多个） + Includes []string // Includes 存储所有 include 语句中的文件名 + Dependencies []*SchemaDesc // Dependencies 存储所有 include 语句对应的解析出的描述符 + Tables []*TableDesc // Tables 存储所有的 table 描述符 + Structs []*StructDesc // Structs 存储所有的 struct 描述符 + Enums []*EnumDesc // Enums 存储所有的 enumeration 描述符 + Unions []*UnionDesc // Unions 存储所有的 union 描述符 + RPCs []*RPCDesc // RPCs 存储所有 rpc service 描述符 +} +``` + +通过访问这些字段，如 `RPCs`，就可以得到 flatbuffers 文件中定义的信息，从而完成一系列相关的工作（如 rpc 桩代码的生成） + +## 工程目录结构 + +``` +. +├── desc.go # 各种节点对应描述符的定义 +├── desc_test.go +├── doc.go +├── docs # 实现文档 +├── errors.go # 错误处理机制 +├── errors_test.go +├── fbsfiles # 存放用于测试的 .fbs 文件 +├── fbs.y # 根据 flatbuffers 的语法写成 +├── fbs.y.go # 由 fbs.y 生成, 用于将 token 流解析为抽象语法树 +├── go.mod +├── go.sum +├── internal +│ └── ast # 存放抽象语法树中各节点的定义以及构造方法 +├── lexer.go # 实现 lexer +├── lexer_test.go +├── linker.go # 实现 linker +├── linker_test.go +├── parse_result.go # 存放解析结果的定义 +├── parser.go # 实现 parser +├── parser_test.go +├── reader.go # 实现 reader +├── README.md +└── scope.go # 实现 scope +``` + +更多内容见 [实现细节](/docs/implementation.zh_CN.md) + +## 应用实例 + +本项目为 trpc-go 提供了支持生成 flatbuffers 相关桩代码的功能 diff --git a/docs/README_en.md b/docs/README_en.md deleted file mode 100644 index 9501017..0000000 --- a/docs/README_en.md +++ /dev/null @@ -1,106 +0,0 @@ -# fbs - -A parser for flatbuffers in Go. - -[中文版](../README.md) - -## Getting Started - -1. Import `package fbs`: - -```go -import "trpc.group/trpc-go/fbs" -``` - -2. Pass in the flatbuffers file list you want to parse. Create a `Parser` and call `ParseFiles`. - -```go -filenames := []string{ - "./file1.fbs", // Pass in a list of flatbuffers files. - "./file2.fbs", -} -p := fbs.NewParser() -fds, err := p.ParseFiles(filenames...) -fd1 := fds[0] // The parsed result(descriptor) of file1.fbs -fd2 := fds[1] // The parsed result(descriptor) of file2.fbs -``` - -You can access the resulting descriptors from `fbs` and get rich information about every method definition of rpc - services, e.g. method names, input/output type, client/server streaming, etc. - -The descriptor `SchemaDesc` for every file has the following fields: - -```go -// SchemaDesc describes a complete .fbs file. -type SchemaDesc struct { - // Schema stores the root node of the AST. - Schema *ast.SchemaNode - // Name stores the .fbs file name. - Name string - // Namespace of schema will change in the course of processing each decl, these will be stored - // in this slice. Decls of table/struct/enum/union will set their own namespaces to be the last - // namespace in this slice. - // See parseResult.createSchemaDescriptor. - Namespaces []string - // Root stores root_type declaration in flatbuffers file. - Root string - // FileExt stores file_extension declaration in flatbuffers file. - FileExt string - // FileIdent stores file_identifier declaration in flatbuffers file. - FileIdent string - // Attrs stores attributes definitions in flatbuffers file. - Attrs []string - // Includes stores all included file names. - Includes []string - // Dependencies stores all descriptors corresponding to included files. - Dependencies []*SchemaDesc - // Tables stores all table descriptors. - Tables []*TableDesc - // Structs stores all struct descriptors. - Structs []*StructDesc - // Enums stores all enum descriptors. - Enums []*EnumDesc - // Unions stores all union descriptors. - Unions []*UnionDesc - // RPCs stores all rpc service descriptors. - RPCs []*RPCDesc -} -``` - -Through accessing these fields such as `RPCs`, you can get information defined in flatbuffers to get related - work done(e.g. generate stub files for rpc services). - -## Project Structure - -``` -. -├── desc.go # Definitions of descriptors for all kinds of node. -├── desc_test.go -├── doc.go -├── docs # Documents of implementation. -├── errors.go # Error handling. -├── errors_test.go -├── fbsfiles # Places .fbs for testing. -├── fbs.y # Hand-written according to the grammar of flatbuffers. -├── fbs.y.go # Generated by fbs.y, used to parse token stream to AST. -├── go.mod -├── go.sum -├── internal -│ └── ast # Stores definitions and constructions of nodes in AST. -├── lexer.go # lexer implementation. -├── lexer_test.go -├── linker.go # linker implementation. -├── linker_test.go -├── parse_result.go # Definition for parsed result. -├── parser.go # parser implementation. -├── parser_test.go -├── reader.go # reader implementation. -├── README.md -└── scope.go # scope implementation. -``` - -Further information see [implementation details](./implementation_en.md) - -## Used in Practice - -This project enables trpc-go to have flatbuffers support. diff --git a/docs/implementation_en.md b/docs/implementation.md similarity index 100% rename from docs/implementation_en.md rename to docs/implementation.md diff --git a/docs/implementation_cn.md b/docs/implementation.zh_CN.md similarity index 100% rename from docs/implementation_cn.md rename to docs/implementation.zh_CN.md