Skip to content

Commit 0394176

Browse files
flemosrflemosr
authored
chore: Adjust README and deduplicate lib docs (#31)
* envoy-types: adjust `README`, use inline links * envoy-types: add `README` symlink to crate directory * envoy-types: use `include_str` for lib docs
1 parent 6c33602 commit 0394176

File tree

3 files changed

+26
-137
lines changed

3 files changed

+26
-137
lines changed

‎README.md‎

Lines changed: 24 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,20 @@
1-
# Envoy Types
1+
# envoy-types
22

3-
Collection of protobuf types and other assets to work with the [Envoy Proxy]
4-
through Rust gRPC services.
3+
Collection of protobuf types and other assets to work with the
4+
[Envoy Proxy](https://www.envoyproxy.io) through Rust gRPC services.
55

66
Among other use cases, this crate can be used to implement an
7-
[Envoy External Authorization] (ExtAuthz) gRPC Server written in Rust.
7+
[Envoy External Authorization](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/ext_authz_filter)
8+
(ExtAuthz) gRPC Server written in Rust.
89

910
[![Crates.io Badge](https://img.shields.io/crates/v/envoy-types)](https://crates.io/crates/envoy-types)
1011
[![Documentation Badge](https://docs.rs/envoy-types/badge.svg)](https://docs.rs/envoy-types)
11-
[![License Badge](https://img.shields.io/crates/l/envoy-types)](LICENSE)
12+
[![License Badge](https://img.shields.io/crates/l/envoy-types)](https://github.com/flemosr/envoy-types/blob/main/LICENSE)
1213
![CI Badge](https://github.com/flemosr/envoy-types/actions/workflows/ci.yml/badge.svg)
1314

14-
[Examples] | [Docs]
15+
[Repository](https://github.com/flemosr/envoy-types) |
16+
[Examples](https://github.com/flemosr/envoy-types/tree/main/examples) |
17+
[Documentation](https://docs.rs/envoy-types/latest/envoy_types)
1518

1619
## Getting Started
1720

@@ -26,20 +29,19 @@ This project's MSRV is `1.75`.
2629
envoy-types = "<envoy-types-version>"
2730
```
2831

29-
The protobuf types made available are already pre-compiled, so you only need the
30-
latest stable Protocol Buffer Compiler (`protoc`) to run the crate's tests.
31-
Generated code may vary across `protoc` versions, and the use of the latest
32-
stable version is enforced by CI.
33-
Installation instructions can be found [here][protoc-install].
32+
The protobuf types made available are already pre-compiled, so the latest stable Protocol Buffer
33+
Compiler (`protoc`) is only needed to run the crate's tests. Generated code may vary across `protoc`
34+
versions, and the use of the latest stable version is enforced by CI. Installation instructions can
35+
be found [here](https://grpc.io/docs/protoc-installation/).
3436

3537
## Examples
3638

3739
The example bellow covers a bare-bones implementation of an Envoy ExtAuthz gRPC
38-
`AuthorizationServer`, with [`tonic`]. A more complete implementation,
39-
including query parameters and header manipulation, can be found at the
40-
[examples] directory.
40+
`AuthorizationServer`, with [`tonic`](https://github.com/hyperium/tonic). A more complete
41+
implementation, including query parameters and header manipulation, can be found at the
42+
[examples](https://github.com/flemosr/envoy-types/tree/main/examples) directory.
4143

42-
```rust
44+
```rust,ignore
4345
use std::env;
4446
use tonic::{transport::Server, Request, Response, Status};
4547
@@ -94,8 +96,9 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
9496

9597
## Compatibility
9698

97-
The table bellow outlines the correspondence between the versions of [`tonic`]
98-
and the compatible versions of [`envoy-types`].
99+
The table bellow outlines the correspondence between the versions of
100+
[`tonic`](https://github.com/hyperium/tonic) and the compatible versions of
101+
[`envoy-types`](https://crates.io/crates/envoy-types).
99102

100103
`tonic` | `envoy-types`
101104
:- | :-
@@ -108,18 +111,10 @@ v0.9 | [v0.2](https://crates.io/crates/envoy-types/0.2.0)
108111

109112
## License
110113

111-
This project is licensed under the [Apache License (Version 2.0)](LICENSE).
114+
This project is licensed under the
115+
[Apache License (Version 2.0)](https://github.com/flemosr/envoy-types/blob/main/LICENSE).
112116

113117
## Contribution
114118

115-
Unless you explicitly state otherwise, any contribution intentionally submitted
116-
for inclusion by you, shall be licensed as Apache-2.0, without any additional
117-
terms or conditions.
118-
119-
[Envoy Proxy]: https://www.envoyproxy.io
120-
[Envoy External Authorization]: https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/ext_authz_filter
121-
[examples]: https://github.com/flemosr/envoy-types/tree/main/examples
122-
[`envoy-types`]: https://crates.io/crates/envoy-types
123-
[Docs]: https://docs.rs/envoy-types/latest/envoy_types
124-
[protoc-install]: https://grpc.io/docs/protoc-installation/
125-
[`tonic`]: https://github.com/hyperium/tonic
119+
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion by
120+
you, shall be licensed as Apache-2.0, without any additional terms or conditions.

‎envoy-types/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../README.md

‎envoy-types/src/lib.rs‎

Lines changed: 1 addition & 108 deletions
Original file line numberDiff line numberDiff line change
@@ -1,111 +1,4 @@
1-
/*!
2-
Collection of protobuf types and other assets to work with the [Envoy Proxy]
3-
through Rust gRPC services.
4-
5-
Among other use cases, this crate can be used to implement an
6-
[Envoy External Authorization] (ExtAuthz) gRPC Server written in Rust.
7-
8-
# Getting Started
9-
10-
### Rust Version
11-
12-
This project's MSRV is `1.75`.
13-
14-
### Dependencies
15-
16-
```toml
17-
[dependencies]
18-
envoy-types = "<envoy-types-version>"
19-
```
20-
21-
The protobuf types made available are already pre-compiled, so you only need the
22-
latest stable Protocol Buffer Compiler (`protoc`) to run the crate's tests.
23-
Generated code may vary across `protoc` versions, and the use of the latest
24-
stable version is enforced by CI.
25-
Installation instructions can be found [here][protoc-install].
26-
27-
# Examples
28-
29-
The example bellow covers a bare-bones implementation of an Envoy ExtAuthz gRPC
30-
`AuthorizationServer`, with [`tonic`]. A more complete implementation, including
31-
query parameters and header manipulation, can be found at the [examples]
32-
directory.
33-
34-
```rust
35-
use std::env;
36-
use tonic::{transport::Server, Request, Response, Status};
37-
38-
use envoy_types::ext_authz::v3::pb::{
39-
Authorization, AuthorizationServer, CheckRequest, CheckResponse,
40-
};
41-
use envoy_types::ext_authz::v3::{CheckRequestExt, CheckResponseExt};
42-
43-
#[derive(Default)]
44-
struct MyServer;
45-
46-
#[tonic::async_trait]
47-
impl Authorization for MyServer {
48-
async fn check(
49-
&self,
50-
request: Request<CheckRequest>,
51-
) -> Result<Response<CheckResponse>, Status> {
52-
let request = request.into_inner();
53-
54-
let client_headers = request
55-
.get_client_headers()
56-
.ok_or_else(|| Status::invalid_argument("client headers not populated by envoy"))?;
57-
58-
let mut request_status = Status::unauthenticated("not authorized");
59-
60-
if let Some(authorization) = client_headers.get("authorization") {
61-
if authorization == "Bearer valid-token" {
62-
request_status = Status::ok("request is valid");
63-
}
64-
}
65-
66-
Ok(Response::new(CheckResponse::with_status(request_status)))
67-
}
68-
}
69-
70-
// #[tokio::main]
71-
// async fn main() -> Result<(), Box<dyn std::error::Error>> {
72-
// let server_port = env::var("SERVER_PORT").unwrap_or("50051".into());
73-
// let addr = format!("0.0.0.0:{server_port}").parse().unwrap();
74-
// let server = MyServer;
75-
76-
// println!("AuthorizationServer listening on {addr}");
77-
78-
// Server::builder()
79-
// .add_service(AuthorizationServer::new(server))
80-
// .serve(addr)
81-
// .await?;
82-
83-
// Ok(())
84-
// }
85-
```
86-
87-
# Compatibility
88-
89-
The table bellow outlines the correspondence between the versions of [`tonic`]
90-
and the compatible versions of [`envoy-types`].
91-
92-
`tonic` | `envoy-types`
93-
:- | :-
94-
v0.14 | [v0.7](https://crates.io/crates/envoy-types/0.7.1)
95-
v0.13 | [v0.6](https://crates.io/crates/envoy-types/0.6.1)
96-
v0.12 | [v0.5](https://crates.io/crates/envoy-types/0.5.6)
97-
v0.11 | [v0.4](https://crates.io/crates/envoy-types/0.4.0)
98-
v0.10 | [v0.3](https://crates.io/crates/envoy-types/0.3.0)
99-
v0.9 | [v0.2](https://crates.io/crates/envoy-types/0.2.0)
100-
101-
[Envoy Proxy]: https://www.envoyproxy.io
102-
[Envoy External Authorization]: https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/ext_authz_filter
103-
[protoc-install]: https://grpc.io/docs/protoc-installation/
104-
[`tonic`]: https://github.com/hyperium/tonic
105-
[examples]: https://github.com/flemosr/envoy-types/tree/main/examples
106-
[`envoy-types`]: https://crates.io/crates/envoy-types
107-
*/
108-
1+
#![doc = include_str!("../README.md")]
1092
#![warn(missing_debug_implementations, rust_2018_idioms)]
1103
#![allow(missing_docs, rustdoc::invalid_html_tags, rustdoc::bare_urls)]
1114

0 commit comments

Comments
 (0)