-
Notifications
You must be signed in to change notification settings - Fork 3
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
eb0f9be
commit b619b82
Showing
70 changed files
with
2,287 additions
and
68,347 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1 +1,5 @@ | ||
examples/rust/target/**/* | ||
**/.env | ||
examples/rust/src/gen/**/* | ||
examples/go/gen/**/* | ||
!examples/rust/src/gen/mod.rs |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,11 +1,19 @@ | ||
# Sift Protobufs | ||
|
||
This repository contains protobufs (protocol buffers) for clients of Sift to interact directly with our gRPC service. If certain protobufs are not yet available for a particular API, please refer to the documentation for our | ||
[REST API](https://docs.siftstack.com/api-docs/rest) which may expose those services via gRPC gateway. | ||
This repository contains protobufs (protocol buffers) for clients of Sift to interact directly with our gRPC service. Documentation for our protobufs can be found [here](https://docs.siftstack.com/ingestion/api). | ||
If certain protobufs are not yet available for a particular API, please refer to the documentation for our [REST API](https://docs.siftstack.com/api-docs/rest) which may expose those services via gRPC gateway. | ||
|
||
For manual installation instructions and usage examples for various languages please refer to the [examples](examples/) directory. If there aren't instructions for your particular programming language consider one of the following options: | ||
For manual installation instructions for a particular programming language, click on one of the following links: | ||
- [Go](/docs/go.md) | ||
- [Rust](/docs/rust.md) | ||
|
||
Please keep in mind that the manual installation instructions aims to be general, and users are encouraged to modify any of the steps that best suits the needs of their project. The instructions do not need to be strictly followed. | ||
|
||
For usage examples you may also refer to the [examples](examples/) directory which demonstrates basic usage of the code generated from compiling the protobufs. | ||
|
||
If there aren't instructions for your particular programming language consider one of the following options: | ||
- Request for the Sift team to include instructions for your language of choice. Keep in mind that there are varying degrees of support for each language throughout the protobuf ecosystem. Depending on the language, support might be totally unavailable. | ||
- Compile the protobufs manually. | ||
- Use our [REST API](https://docs.siftstack.com/api-docs/rest). | ||
|
||
In the near future we will provide more installation options. | ||
In the near future we will plan to provide more installation options. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,94 @@ | ||
# Sift Protobuf Installation for Go | ||
|
||
Before proceeding with installation, you will need to ensure that you have the [buf CLI](https://buf.build/docs/installation) installed. | ||
|
||
If `$ which buf` generates a path to the executable, you may proceed to the installation steps. | ||
|
||
To install Sift protobufs in your project: | ||
|
||
1. Clone this repository onto your local machine and `cd` into it: | ||
|
||
```bash | ||
$ git clone https://github.com/sift-stack/sift | ||
$ cd sift | ||
``` | ||
|
||
2. Assuming the path to the root of your Go project is `$PROJECT_DIR`, run the following command in the `sift` directory that you just cloned: | ||
|
||
```bash | ||
$ buf export protos --output=$PROJECT_DIR/protos --config protos/buf.yaml | ||
``` | ||
|
||
The Sift protos can and its imports can now be found in your `$PROJECT_DIR/protos` directory. | ||
|
||
3. Copy the `buf` template for Go to your project directory: | ||
|
||
```bash | ||
$ cp buf_templates/buf.gen.go.yaml $PROJECT_DIR/buf.gen.yaml | ||
``` | ||
|
||
4. `cd` into your Go project at `$PROJECT_DIR`. | ||
|
||
5. Once inside of your Go project, you'll need to modify the `managed.enabled.go_package_prefix.default` value of your `buf.gen.yaml` file to | ||
have the package prefix named after your Go module. If our Go module's name, for example, is `github.com/example_project`, then change the `buf.gen.yaml` to `github.com/example_project/gen/protos/go`. Your | ||
`buf.gen.yaml` should now look like the following: | ||
|
||
```yaml | ||
version: v1 | ||
managed: | ||
enabled: true | ||
go_package_prefix: | ||
default: "github.com/example_project/gen/protos/go" | ||
plugins: | ||
- plugin: buf.build/protocolbuffers/go:v1.28.1 | ||
out: gen/protos/go | ||
opt: paths=source_relative | ||
- plugin: go-vtproto | ||
out: gen/protos/go | ||
opt: paths=source_relative | ||
- plugin: buf.build/grpc-ecosystem/gateway:v2.16.2 | ||
out: gen/protos/go | ||
opt: paths=source_relative | ||
``` | ||
Refer to your `go.mod` file for the name of your Go module. | ||
|
||
6. Inside of the root of your project directory you may now compile your protobufs: | ||
|
||
```bash | ||
$ buf generate protos | ||
``` | ||
|
||
Your project up to this point should look like the following (full depth not shown): | ||
|
||
``` | ||
example_project | ||
├─ buf.gen.yaml | ||
├─ gen | ||
│ └─ protos | ||
│ └─ go | ||
├─ go.sum | ||
├─ go.mod | ||
└─ protos | ||
├─ protoc-gen-openapiv2 | ||
│ └─ options | ||
│ └─ api | ||
└─ sift | ||
├─ runs | ||
├─ notifications | ||
├─ annotations | ||
├─ users | ||
├─ common | ||
├─ assets | ||
├─ tags | ||
└─ annotation_logs | ||
``` | ||
|
||
7. Install any dependencies you might be missing that the generated code requires: | ||
|
||
```bash | ||
$ go get -d ./... | ||
``` | ||
|
||
8. Now your project should be ready to use the generated Go code to interact with Sift's gRPC API. Please refer to the [example code](/examples/go) for usage. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,106 @@ | ||
# Sift Protobuf Installation for Rust | ||
|
||
Before proceeding with installation, you will need to ensure that you have the [buf CLI](https://buf.build/docs/installation) installed. | ||
|
||
If `$ which buf` generates a path to the executable, you may proceed to the installation steps. | ||
|
||
To install Sift protobufs in your project: | ||
|
||
1. Clone this repository onto your local machine and `cd` into it: | ||
|
||
```bash | ||
$ git clone https://github.com/sift-stack/sift | ||
$ cd sift | ||
``` | ||
|
||
2. Assuming the path to the root of your Rust project is `$PROJECT_DIR`, run the following command in the `sift` directory that you just cloned: | ||
|
||
```bash | ||
$ buf export protos --output=$PROJECT_DIR/protos --config protos/buf.yaml | ||
``` | ||
|
||
The Sift protos can and its imports can now be found in your `$PROJECT_DIR/protos` directory. | ||
|
||
3. Copy the `buf` template for Rust to your project directory: | ||
|
||
```bash | ||
$ cp buf_templates/buf.gen.go.yaml $PROJECT_DIR/buf.gen.yaml | ||
``` | ||
|
||
4. `cd` into your Rust project at `$PROJECT_DIR`. | ||
|
||
5. Once inside of your Rust project, declare a module called `gen` in your `main.rs` (unless you're crate is a lib-crate) and create a `src/gen/mod.rs` file. | ||
|
||
```rust | ||
// main.go | ||
|
||
/// Sift generated code | ||
mod gen; | ||
``` | ||
|
||
Refer to the `buf.gen.yaml` in your project root if you need to modify the output path for the compiled protos. | ||
|
||
|
||
6. Inside of the root of your project directory you may now compile your protobufs: | ||
|
||
```bash | ||
$ buf generate protos | ||
``` | ||
|
||
Your project up to this point should look like the following (full depth not shown): | ||
|
||
``` | ||
example_project | ||
├─ src | ||
│ ├─ main.rs | ||
│ └─ gen | ||
│ ├─ sift.common.type.v1.rs | ||
│ ├─ sift.runs.v2.rs | ||
│ ├─ sift.annotation_logs.v1.rs | ||
│ ├─ sift.runs.v2.tonic.rs | ||
│ ├─ sift.users.v2.rs | ||
│ ├─ mod.rs | ||
│ ├─ sift.tags.v1.rs | ||
│ ├─ sift.assets.v1.tonic.rs | ||
│ ├─ sift.assets.v1.rs | ||
│ ├─ sift.notifications.v1.tonic.rs | ||
│ ├─ sift.users.v2.tonic.rs | ||
│ ├─ sift.annotation_logs.v1.tonic.rs | ||
│ ├─ grpc.gateway.protoc_gen_openapiv2.options.rs | ||
│ ├─ sift.notifications.v1.rs | ||
│ ├─ sift.annotations.v1.tonic.rs | ||
│ ├─ google.api.rs | ||
│ └─ sift.annotations.v1.rs | ||
├─ buf.gen.yaml | ||
├─ README.md | ||
├─ Cargo.lock | ||
└─ Cargo.toml | ||
2 directories, 22 files | ||
``` | ||
|
||
7. Ensure you have the following dependencies installed: | ||
|
||
```toml | ||
[package] | ||
name = "sift_cli" | ||
version = "0.1.0" | ||
edition = "2021" | ||
|
||
# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html | ||
|
||
[dependencies] | ||
async-trait = "0.1.79" | ||
prost = "0.12.4" | ||
prost-types = "0.12.4" | ||
tonic = { version = "0.11.0", features = ["tls", "tls-roots", "tls-webpki-roots"] } | ||
``` | ||
|
||
8. Declare the modules that will import the generated code in your `src/gen/mod.rs`. For example, we wish to use the generated `annotations` code for this example: | ||
|
||
```rust | ||
#[path = "sift.annotations.v1.rs"] | ||
pub mod annotations; | ||
``` | ||
|
||
9. Now your project should be ready to use the generated Rust code to interact with Sift's gRPC API. Please refer to the [example code](/examples/rust/) for usage. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,96 +1,32 @@ | ||
# Sift Go Example | ||
|
||
Before proceeding with installation, you will need to ensure that you have the [buf CLI](https://buf.build/docs/installation) installed. | ||
To run this example ensure that you have Go and the [buf CLI](https://buf.build/docs/installation) installed as well as having your | ||
Sift API key ready. If you need a Sift API key please refer to [these instructions](https://help.siftstack.com/en/articles/8600475-api-keys). | ||
|
||
If `$ which buf` generates a path to the executable, you may proceed to the installation steps. | ||
|
||
To install Sift protobufs in your project: | ||
|
||
1. Clone this repository onto your local machine and `cd` into it: | ||
|
||
```bash | ||
$ git clone https://github.com/sift-stack/sift | ||
$ cd sift | ||
``` | ||
|
||
2. Assuming the path to the root of your Go project is `$PROJECT_DIR`, run the following command in the `sift` directory that you just cloned: | ||
Once those are installed and your working directory is this project's root, compile the protobufs: | ||
|
||
```bash | ||
$ buf export protos --output=$PROJECT_DIR/protos --config protos/buf.yaml | ||
$ buf generate protos | ||
``` | ||
|
||
The Sift protos can and its imports can now be found in your `$PROJECT_DIR/protos` directory. | ||
|
||
3. Copy the `buf` template for Go to your project directory: | ||
Install dependencies: | ||
|
||
```bash | ||
$ cp buf_templates/buf.gen.go.yaml $PROJECT_DIR/buf.gen.yaml | ||
``` | ||
|
||
4. `cd` into your Go project at `$PROJECT_DIR`. | ||
|
||
5. Once inside of your Go project, you'll need to modify the `managed.enabled.go_package_prefix.default` value of your `buf.gen.yaml` file to | ||
have the package prefix named after your Go module. If our Go module's name, for example, is `github.com/sift-go-cli`, then change the `buf.gen.yaml` to `github.com/sift-go-cli/gen/protos/go`. Your | ||
`buf.gen.yaml` should now look like the following: | ||
|
||
```yaml | ||
version: v1 | ||
managed: | ||
enabled: true | ||
go_package_prefix: | ||
default: "github.com/sift-go-cli/gen/protos/go" | ||
plugins: | ||
- plugin: buf.build/protocolbuffers/go:v1.28.1 | ||
out: gen/protos/go | ||
opt: paths=source_relative | ||
- plugin: go-vtproto | ||
out: gen/protos/go | ||
opt: paths=source_relative | ||
- plugin: buf.build/grpc-ecosystem/gateway:v2.16.2 | ||
out: gen/protos/go | ||
opt: paths=source_relative | ||
$ go get -d ./... | ||
``` | ||
|
||
Refer to your `go.mod` file for the name of your Go module. | ||
|
||
6. Inside of the root of your project directory you may now compile your protobufs: | ||
Create your `.env` file: | ||
|
||
```bash | ||
$ buf generate protos | ||
$ cp .env-example .env | ||
``` | ||
|
||
Your project up to this point should look like the following (full depth not shown): | ||
Be sure to set the appropriate environment variables in your `.env` file depending on the environment you're using. Comments | ||
meant to serve as guides can be found in the `.env-example` file. | ||
|
||
``` | ||
sift-go-cli | ||
├─ buf.gen.yaml | ||
├─ gen | ||
│ └─ protos | ||
│ └─ go | ||
├─ go.sum | ||
├─ go.mod | ||
└─ protos | ||
├─ protoc-gen-openapiv2 | ||
│ └─ options | ||
│ └─ api | ||
└─ sift | ||
├─ runs | ||
├─ notifications | ||
├─ annotations | ||
├─ users | ||
├─ common | ||
├─ assets | ||
├─ tags | ||
└─ annotation_logs | ||
``` | ||
|
||
7. Install any dependencies you might be missing that the generated code requires: | ||
Now execute the program by providing the partial string of the annotations you wish to query. In the following example | ||
we'll be querying for all annotations whose name matches the `voltage` substring in a case-insensitive manner. | ||
|
||
```bash | ||
$ go get -d ./... | ||
$ go run . voltage | ||
``` | ||
|
||
8. Now your project should be ready to use the generated Go code to interact with Sift's gRPC API. Please refer to the example code for usage. | ||
If you are cloning the example repository, be sure to `$ cp .example.env .env` and set the appropriate variables. Comments in the `.example.env` files | ||
may prove useful. |
Oops, something went wrong.