diff --git a/Cargo.lock b/Cargo.lock index 4e9a81ba..43007948 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -3768,6 +3768,15 @@ dependencies = [ "syn 2.0.119", ] +[[package]] +name = "prost-types" +version = "0.14.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f94967dc7688f3054c7fac87473ffae4cc4c3904800e2d9f5b857246d8963b0a" +dependencies = [ + "prost", +] + [[package]] name = "protobuf" version = "3.7.2" @@ -4973,6 +4982,7 @@ dependencies = [ "http-body-util", "linkme", "prost", + "prost-types", "serde", "serde_json", "smallvec", @@ -5018,6 +5028,7 @@ dependencies = [ "parking_lot", "pin-project-lite", "prost", + "prost-types", "rustls", "scc", "send_wrapper", diff --git a/Cargo.toml b/Cargo.toml index 0c501a04..8cf70d4a 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -115,6 +115,7 @@ pin-project-lite = "0.2.16" proc-macro2 = { version = "1" } prometheus = "0.14.0" prost = "0.14.1" +prost-types = "0.14.1" quinn = "0.11.12" quote = { version = "1" } rcgen = { version = "0.14.10", default-features = false, features = ["aws_lc_rs"] } diff --git a/tako-rs-core/Cargo.toml b/tako-rs-core/Cargo.toml index 47cde74f..e1c98cde 100644 --- a/tako-rs-core/Cargo.toml +++ b/tako-rs-core/Cargo.toml @@ -39,6 +39,7 @@ mime_guess = { workspace = true } parking_lot = { workspace = true } pin-project-lite = { workspace = true } prost = { workspace = true, optional = true } +prost-types = { workspace = true, optional = true } rustls = { workspace = true, optional = true } scc = { workspace = true } send_wrapper = { workspace = true, optional = true } @@ -78,7 +79,7 @@ simd = ["tako-rs/simd", "simd-sonic", "simd-json-impl"] simd-sonic = ["tako-rs/simd-sonic", "dep:sonic-rs"] simd-json-impl = ["tako-rs/simd-json-impl"] tls = ["tako-rs/tls", "dep:rustls"] -grpc = ["tako-rs/grpc", "protobuf", "dep:base64"] +grpc = ["tako-rs/grpc", "protobuf", "dep:base64", "dep:prost-types"] queue-cron = ["tako-rs/queue-cron", "dep:cron", "dep:chrono"] http3 = ["tako-rs/http3", "dep:rustls"] webtransport = ["tako-rs/webtransport", "http3"] diff --git a/tako-rs-core/src/grpc/health.rs b/tako-rs-core/src/grpc/health.rs index 86acb14b..4352cd18 100644 --- a/tako-rs-core/src/grpc/health.rs +++ b/tako-rs-core/src/grpc/health.rs @@ -1,26 +1,107 @@ -//! Per-service status map for a `grpc.health.v1.Health` service; serve it from your own -//! `Check` and `Watch` handlers. +//! `grpc.health.v1.Health`: register Check, Watch, and List on an ordinary router. use std::sync::Arc; +use futures_util::Stream; use scc::HashMap as SccHashMap; +use tokio::sync::watch; + +use super::GrpcDeadline; +use super::GrpcRequest; +use super::GrpcResponse; +use super::GrpcServerStream; +use super::GrpcStatus; +use super::GrpcStatusCode; +use crate::router::Router; + +mod protocol; +pub use protocol::*; + +/// Encoded health schema for reflection registration. +pub const FILE_DESCRIPTOR_SET: &[u8] = include_bytes!("proto/health.bin"); #[derive(Debug, Clone, Copy, Default, PartialEq, Eq)] +#[repr(i32)] pub enum ServingStatus { - Unknown, + Unknown = 0, #[default] - Serving, - NotServing, - ServiceUnknown, + Serving = 1, + NotServing = 2, + ServiceUnknown = 3, } /// Service statuses; clones share one map. -#[derive(Clone, Default)] +#[derive(Clone)] pub struct HealthRegistry { inner: Arc>, + updates: Arc>, +} + +impl Default for HealthRegistry { + fn default() -> Self { + Self { + inner: Arc::default(), + updates: Arc::new(watch::channel(()).0), + } + } } impl HealthRegistry { + /// Registers Check, Watch, and List. + pub fn register(&self, router: &mut Router) { + let registry = self.clone(); + router.post( + "/grpc.health.v1.Health/Check", + move |deadline: Option, request: GrpcRequest| { + let status = registry.status_of(&request.message.service); + async move { + if deadline.is_some_and(|deadline| deadline.remaining().is_zero()) { + return GrpcResponse::error(GrpcStatusCode::DeadlineExceeded, "deadline exceeded"); + } + if status == ServingStatus::ServiceUnknown { + GrpcResponse::error(GrpcStatusCode::NotFound, "unknown service") + } else { + GrpcResponse::ok(HealthCheckResponse { + status: status as i32, + }) + } + } + }, + ); + let registry = self.clone(); + router.post( + "/grpc.health.v1.Health/Watch", + move |deadline: Option, request: GrpcRequest| { + let stream = registry.watch(request.message.service); + async move { GrpcServerStream::new(stream).with_deadline(deadline) } + }, + ); + let registry = self.clone(); + router.post( + "/grpc.health.v1.Health/List", + move |deadline: Option, _: GrpcRequest| { + let statuses = registry + .snapshot() + .into_iter() + .map(|(name, status)| { + ( + name, + HealthCheckResponse { + status: status as i32, + }, + ) + }) + .collect(); + async move { + if deadline.is_some_and(|deadline| deadline.remaining().is_zero()) { + return GrpcResponse::error(GrpcStatusCode::DeadlineExceeded, "deadline exceeded"); + } + GrpcResponse::ok(HealthListResponse { statuses }) + } + }, + ); + } + pub fn new() -> Self { Self::default() } @@ -29,6 +110,7 @@ impl HealthRegistry { pub fn set_status(&self, service: impl Into, status: ServingStatus) { // `insert_sync` would keep the first status ever set. self.inner.upsert_sync(service.into(), status); + self.updates.send_replace(()); } /// `ServiceUnknown` for a service that was never set. @@ -47,4 +129,33 @@ impl HealthRegistry { }); out } + + /// Yields the current status immediately, then changes until dropped. + /// Unknown services stay subscribed; slow readers see the latest status. + pub fn watch>( + &self, + service: S, + ) -> impl Stream> + Send + 'static + use { + let state = (self.clone(), self.updates.subscribe(), service.into(), None); + futures_util::stream::unfold( + state, + |(registry, mut updates, service, mut previous)| async move { + loop { + if previous.is_some() { + updates.changed().await.ok()?; + } + let status = registry.status_of(&service); + if previous != Some(status) { + previous = Some(status); + return Some(( + Ok(HealthCheckResponse { + status: status as i32, + }), + (registry, updates, service, previous), + )); + } + } + }, + ) + } } diff --git a/tako-rs-core/src/grpc/health/protocol.rs b/tako-rs-core/src/grpc/health/protocol.rs new file mode 100644 index 00000000..9fd96329 --- /dev/null +++ b/tako-rs-core/src/grpc/health/protocol.rs @@ -0,0 +1,36 @@ +//! Wire messages for . + +/// Service to check; the empty name selects the whole server. +#[derive(Clone, PartialEq, prost::Message)] +pub struct HealthCheckRequest { + #[prost(string, tag = "1")] + pub service: String, +} + +#[derive(Clone, Copy, PartialEq, prost::Message)] +pub struct HealthCheckResponse { + #[prost(enumeration = "health_check_response::ServingStatus", tag = "1")] + pub status: i32, +} + +pub mod health_check_response { + /// The wire default is `Unknown`; the registry's convenience enum defaults to `Serving`. + #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, prost::Enumeration)] + #[repr(i32)] + pub enum ServingStatus { + Unknown = 0, + Serving = 1, + NotServing = 2, + ServiceUnknown = 3, + } +} + +#[derive(Clone, Copy, PartialEq, prost::Message)] +pub struct HealthListRequest {} + +/// Snapshot of explicitly registered services. +#[derive(Clone, PartialEq, prost::Message)] +pub struct HealthListResponse { + #[prost(btree_map = "string, message", tag = "1")] + pub statuses: std::collections::BTreeMap, +} diff --git a/tako-rs-core/src/grpc/proto/LICENSE b/tako-rs-core/src/grpc/proto/LICENSE new file mode 100644 index 00000000..d6456956 --- /dev/null +++ b/tako-rs-core/src/grpc/proto/LICENSE @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/tako-rs-core/src/grpc/proto/README.md b/tako-rs-core/src/grpc/proto/README.md new file mode 100644 index 00000000..c37e4b5c --- /dev/null +++ b/tako-rs-core/src/grpc/proto/README.md @@ -0,0 +1,14 @@ +The schemas are from [grpc-proto](https://github.com/grpc/grpc-proto). The Rust +message types are checked in alongside the services; consumers do not run protoc. +The descriptor sets let reflection describe itself and the health service. + +Regenerate the descriptors from the repository root when changing a schema: + +```sh +protoc --proto_path=tako-rs-core/src/grpc/proto \ + --descriptor_set_out=tako-rs-core/src/grpc/proto/reflection.bin \ + grpc/reflection/v1/reflection.proto grpc/reflection/v1alpha/reflection.proto +protoc --proto_path=tako-rs-core/src/grpc/proto \ + --descriptor_set_out=tako-rs-core/src/grpc/proto/health.bin \ + grpc/health/v1/health.proto +``` diff --git a/tako-rs-core/src/grpc/proto/grpc/health/v1/health.proto b/tako-rs-core/src/grpc/proto/grpc/health/v1/health.proto new file mode 100644 index 00000000..288ce7c9 --- /dev/null +++ b/tako-rs-core/src/grpc/proto/grpc/health/v1/health.proto @@ -0,0 +1,92 @@ +// Copyright 2015 The gRPC Authors +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// The canonical version of this proto can be found at +// https://github.com/grpc/grpc-proto/blob/master/grpc/health/v1/health.proto + +syntax = "proto3"; + +package grpc.health.v1; + +option csharp_namespace = "Grpc.Health.V1"; +option go_package = "google.golang.org/grpc/health/grpc_health_v1"; +option java_multiple_files = true; +option java_outer_classname = "HealthProto"; +option java_package = "io.grpc.health.v1"; +option objc_class_prefix = "GrpcHealthV1"; + +message HealthCheckRequest { + string service = 1; +} + +message HealthCheckResponse { + enum ServingStatus { + UNKNOWN = 0; + SERVING = 1; + NOT_SERVING = 2; + SERVICE_UNKNOWN = 3; // Used only by the Watch method. + } + ServingStatus status = 1; +} + +message HealthListRequest {} + +message HealthListResponse { + // statuses contains all the services and their respective status. + map statuses = 1; +} + +// Health is gRPC's mechanism for checking whether a server is able to handle +// RPCs. Its semantics are documented in +// https://github.com/grpc/grpc/blob/master/doc/health-checking.md. +service Health { + // Check gets the health of the specified service. If the requested service + // is unknown, the call will fail with status NOT_FOUND. If the caller does + // not specify a service name, the server should respond with its overall + // health status. + // + // Clients should set a deadline when calling Check, and can declare the + // server unhealthy if they do not receive a timely response. + rpc Check(HealthCheckRequest) returns (HealthCheckResponse); + + // List provides a non-atomic snapshot of the health of all the available + // services. + // + // The server may respond with a RESOURCE_EXHAUSTED error if too many services + // exist. + // + // Clients should set a deadline when calling List, and can declare the server + // unhealthy if they do not receive a timely response. + // + // Clients should keep in mind that the list of health services exposed by an + // application can change over the lifetime of the process. + rpc List(HealthListRequest) returns (HealthListResponse); + + // Performs a watch for the serving status of the requested service. + // The server will immediately send back a message indicating the current + // serving status. It will then subsequently send a new message whenever + // the service's serving status changes. + // + // If the requested service is unknown when the call is received, the + // server will send a message setting the serving status to + // SERVICE_UNKNOWN but will *not* terminate the call. If at some + // future point, the serving status of the service becomes known, the + // server will send a new message with the service's serving status. + // + // If the call terminates with status UNIMPLEMENTED, then clients + // should assume this method is not supported and should not retry the + // call. If the call terminates with any other status (including OK), + // clients should retry the call with appropriate exponential backoff. + rpc Watch(HealthCheckRequest) returns (stream HealthCheckResponse); +} diff --git a/tako-rs-core/src/grpc/proto/grpc/reflection/v1/reflection.proto b/tako-rs-core/src/grpc/proto/grpc/reflection/v1/reflection.proto new file mode 100644 index 00000000..f9f349fe --- /dev/null +++ b/tako-rs-core/src/grpc/proto/grpc/reflection/v1/reflection.proto @@ -0,0 +1,146 @@ +// Copyright 2016 The gRPC Authors +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// Service exported by server reflection. A more complete description of how +// server reflection works can be found at +// https://github.com/grpc/grpc/blob/master/doc/server-reflection.md +// +// The canonical version of this proto can be found at +// https://github.com/grpc/grpc-proto/blob/master/grpc/reflection/v1/reflection.proto + +syntax = "proto3"; + +package grpc.reflection.v1; + +option go_package = "google.golang.org/grpc/reflection/grpc_reflection_v1"; +option java_multiple_files = true; +option java_package = "io.grpc.reflection.v1"; +option java_outer_classname = "ServerReflectionProto"; + +service ServerReflection { + // The reflection service is structured as a bidirectional stream, ensuring + // all related requests go to a single server. + rpc ServerReflectionInfo(stream ServerReflectionRequest) + returns (stream ServerReflectionResponse); +} + +// The message sent by the client when calling ServerReflectionInfo method. +message ServerReflectionRequest { + string host = 1; + // To use reflection service, the client should set one of the following + // fields in message_request. The server distinguishes requests by their + // defined field and then handles them using corresponding methods. + oneof message_request { + // Find a proto file by the file name. + string file_by_filename = 3; + + // Find the proto file that declares the given fully-qualified symbol name. + // This field should be a fully-qualified symbol name + // (e.g. .[.] or .). + string file_containing_symbol = 4; + + // Find the proto file which defines an extension extending the given + // message type with the given field number. + ExtensionRequest file_containing_extension = 5; + + // Finds the tag numbers used by all known extensions of the given message + // type, and appends them to ExtensionNumberResponse in an undefined order. + // Its corresponding method is best-effort: it's not guaranteed that the + // reflection service will implement this method, and it's not guaranteed + // that this method will provide all extensions. Returns + // StatusCode::UNIMPLEMENTED if it's not implemented. + // This field should be a fully-qualified type name. The format is + // . + string all_extension_numbers_of_type = 6; + + // List the full names of registered services. The content will not be + // checked. + string list_services = 7; + } +} + +// The type name and extension number sent by the client when requesting +// file_containing_extension. +message ExtensionRequest { + // Fully-qualified type name. The format should be . + string containing_type = 1; + int32 extension_number = 2; +} + +// The message sent by the server to answer ServerReflectionInfo method. +message ServerReflectionResponse { + string valid_host = 1; + ServerReflectionRequest original_request = 2; + // The server sets one of the following fields according to the message_request + // in the request. + oneof message_response { + // This message is used to answer file_by_filename, file_containing_symbol, + // file_containing_extension requests with transitive dependencies. + // As the repeated label is not allowed in oneof fields, we use a + // FileDescriptorResponse message to encapsulate the repeated fields. + // The reflection service is allowed to avoid sending FileDescriptorProtos + // that were previously sent in response to earlier requests in the stream. + FileDescriptorResponse file_descriptor_response = 4; + + // This message is used to answer all_extension_numbers_of_type requests. + ExtensionNumberResponse all_extension_numbers_response = 5; + + // This message is used to answer list_services requests. + ListServiceResponse list_services_response = 6; + + // This message is used when an error occurs. + ErrorResponse error_response = 7; + } +} + +// Serialized FileDescriptorProto messages sent by the server answering +// a file_by_filename, file_containing_symbol, or file_containing_extension +// request. +message FileDescriptorResponse { + // Serialized FileDescriptorProto messages. We avoid taking a dependency on + // descriptor.proto, which uses proto2 only features, by making them opaque + // bytes instead. + repeated bytes file_descriptor_proto = 1; +} + +// A list of extension numbers sent by the server answering +// all_extension_numbers_of_type request. +message ExtensionNumberResponse { + // Full name of the base type, including the package name. The format + // is . + string base_type_name = 1; + repeated int32 extension_number = 2; +} + +// A list of ServiceResponse sent by the server answering list_services request. +message ListServiceResponse { + // The information of each service may be expanded in the future, so we use + // ServiceResponse message to encapsulate it. + repeated ServiceResponse service = 1; +} + +// The information of a single service used by ListServiceResponse to answer +// list_services request. +message ServiceResponse { + // Full name of a registered service, including its package name. The format + // is . + string name = 1; +} + +// The error code and error message sent by the server when an error occurs. +message ErrorResponse { + // This field uses the error codes defined in grpc::StatusCode. + int32 error_code = 1; + string error_message = 2; +} diff --git a/tako-rs-core/src/grpc/proto/grpc/reflection/v1alpha/reflection.proto b/tako-rs-core/src/grpc/proto/grpc/reflection/v1alpha/reflection.proto new file mode 100644 index 00000000..e8384db3 --- /dev/null +++ b/tako-rs-core/src/grpc/proto/grpc/reflection/v1alpha/reflection.proto @@ -0,0 +1,145 @@ +// Copyright 2016 The gRPC Authors +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// Service exported by server reflection + + +// Warning: this entire file is deprecated. Use this instead: +// https://github.com/grpc/grpc-proto/blob/master/grpc/reflection/v1/reflection.proto + +syntax = "proto3"; + +package grpc.reflection.v1alpha; + +option deprecated = true; +option go_package = "google.golang.org/grpc/reflection/grpc_reflection_v1alpha"; +option java_multiple_files = true; +option java_package = "io.grpc.reflection.v1alpha"; +option java_outer_classname = "ServerReflectionProto"; + +service ServerReflection { + // The reflection service is structured as a bidirectional stream, ensuring + // all related requests go to a single server. + rpc ServerReflectionInfo(stream ServerReflectionRequest) + returns (stream ServerReflectionResponse); +} + +// The message sent by the client when calling ServerReflectionInfo method. +message ServerReflectionRequest { + string host = 1; + // To use reflection service, the client should set one of the following + // fields in message_request. The server distinguishes requests by their + // defined field and then handles them using corresponding methods. + oneof message_request { + // Find a proto file by the file name. + string file_by_filename = 3; + + // Find the proto file that declares the given fully-qualified symbol name. + // This field should be a fully-qualified symbol name + // (e.g. .[.] or .). + string file_containing_symbol = 4; + + // Find the proto file which defines an extension extending the given + // message type with the given field number. + ExtensionRequest file_containing_extension = 5; + + // Finds the tag numbers used by all known extensions of extendee_type, and + // appends them to ExtensionNumberResponse in an undefined order. + // Its corresponding method is best-effort: it's not guaranteed that the + // reflection service will implement this method, and it's not guaranteed + // that this method will provide all extensions. Returns + // StatusCode::UNIMPLEMENTED if it's not implemented. + // This field should be a fully-qualified type name. The format is + // . + string all_extension_numbers_of_type = 6; + + // List the full names of registered services. The content will not be + // checked. + string list_services = 7; + } +} + +// The type name and extension number sent by the client when requesting +// file_containing_extension. +message ExtensionRequest { + // Fully-qualified type name. The format should be . + string containing_type = 1; + int32 extension_number = 2; +} + +// The message sent by the server to answer ServerReflectionInfo method. +message ServerReflectionResponse { + string valid_host = 1; + ServerReflectionRequest original_request = 2; + // The server set one of the following fields according to the message_request + // in the request. + oneof message_response { + // This message is used to answer file_by_filename, file_containing_symbol, + // file_containing_extension requests with transitive dependencies. As + // the repeated label is not allowed in oneof fields, we use a + // FileDescriptorResponse message to encapsulate the repeated fields. + // The reflection service is allowed to avoid sending FileDescriptorProtos + // that were previously sent in response to earlier requests in the stream. + FileDescriptorResponse file_descriptor_response = 4; + + // This message is used to answer all_extension_numbers_of_type request. + ExtensionNumberResponse all_extension_numbers_response = 5; + + // This message is used to answer list_services request. + ListServiceResponse list_services_response = 6; + + // This message is used when an error occurs. + ErrorResponse error_response = 7; + } +} + +// Serialized FileDescriptorProto messages sent by the server answering +// a file_by_filename, file_containing_symbol, or file_containing_extension +// request. +message FileDescriptorResponse { + // Serialized FileDescriptorProto messages. We avoid taking a dependency on + // descriptor.proto, which uses proto2 only features, by making them opaque + // bytes instead. + repeated bytes file_descriptor_proto = 1; +} + +// A list of extension numbers sent by the server answering +// all_extension_numbers_of_type request. +message ExtensionNumberResponse { + // Full name of the base type, including the package name. The format + // is . + string base_type_name = 1; + repeated int32 extension_number = 2; +} + +// A list of ServiceResponse sent by the server answering list_services request. +message ListServiceResponse { + // The information of each service may be expanded in the future, so we use + // ServiceResponse message to encapsulate it. + repeated ServiceResponse service = 1; +} + +// The information of a single service used by ListServiceResponse to answer +// list_services request. +message ServiceResponse { + // Full name of a registered service, including its package name. The format + // is . + string name = 1; +} + +// The error code and error message sent by the server when an error occurs. +message ErrorResponse { + // This field uses the error codes defined in grpc::StatusCode. + int32 error_code = 1; + string error_message = 2; +} diff --git a/tako-rs-core/src/grpc/proto/health.bin b/tako-rs-core/src/grpc/proto/health.bin new file mode 100644 index 00000000..c177a115 Binary files /dev/null and b/tako-rs-core/src/grpc/proto/health.bin differ diff --git a/tako-rs-core/src/grpc/proto/reflection.bin b/tako-rs-core/src/grpc/proto/reflection.bin new file mode 100644 index 00000000..5e5d24c2 Binary files /dev/null and b/tako-rs-core/src/grpc/proto/reflection.bin differ diff --git a/tako-rs-core/src/grpc/reflection.rs b/tako-rs-core/src/grpc/reflection.rs index 194a5a01..c48d0a74 100644 --- a/tako-rs-core/src/grpc/reflection.rs +++ b/tako-rs-core/src/grpc/reflection.rs @@ -1,17 +1,35 @@ -//! Descriptor registry for `grpc.reflection.v1`: answers `list_services`, `file_by_filename` -//! and `file_containing_symbol`, while the RPC itself is up to you. +//! Standard bidirectional server reflection, including descriptor dependencies and extensions. use std::sync::Arc; +use descriptors::Descriptors; +use descriptors::File; +use descriptors::error; +use futures_util::StreamExt; use parking_lot::RwLock; -use scc::HashMap as SccHashMap; +use prost::Message; +use server_reflection_request::MessageRequest; +use server_reflection_response::MessageResponse; + +use super::GrpcBidi; +use super::GrpcDeadline; +use super::GrpcStatus; +use super::GrpcStatusCode; +use crate::router::Router; + +mod descriptors; +mod error; +mod protocol; +pub use error::DescriptorError; +pub use protocol::*; + +/// Encoded v1 and v1alpha reflection schemas. +pub const FILE_DESCRIPTOR_SET: &[u8] = include_bytes!("proto/reflection.bin"); /// Services and file descriptors to expose; clones share one registry. #[derive(Clone, Default)] pub struct ReflectionRegistry { - services: Arc>>, - files: Arc>>, - symbols: Arc>, + inner: Arc>, } impl ReflectionRegistry { @@ -19,35 +37,175 @@ impl ReflectionRegistry { Self::default() } + /// Registers the v1 and v1alpha routes and their own descriptors. + pub fn register(&self, router: &mut Router) { + self + .register_encoded_file_descriptor_set(FILE_DESCRIPTOR_SET) + .expect("valid built-in reflection descriptors"); + for path in [ + "/grpc.reflection.v1.ServerReflection/ServerReflectionInfo", + "/grpc.reflection.v1alpha.ServerReflection/ServerReflectionInfo", + ] { + let registry = self.clone(); + router.post( + path, + move |deadline: Option, + bidi: GrpcBidi| { + let registry = registry.clone(); + async move { + bidi + .respond(move |requests| { + requests.map(move |request| { + request + .map(|request| registry.respond(request)) + .map_err(GrpcStatus::from) + }) + }) + .with_deadline(deadline) + } + }, + ); + } + } + + /// Imports a `FileDescriptorSet`, indexing services, symbols, and extensions automatically. + /// Generate it with `protoc --include_imports`; missing imports produce `NotFound` replies. + /// Invalid protobuf or unnamed files return an error without changing the registry. + pub fn register_encoded_file_descriptor_set(&self, bytes: &[u8]) -> Result<(), DescriptorError> { + let set = EncodedDescriptorSet::decode(bytes)?; + let mut files = Vec::with_capacity(set.files.len()); + for bytes in set.files { + let descriptor = prost_types::FileDescriptorProto::decode(bytes.as_slice())?; + let name = descriptor.name().to_owned(); + if name.is_empty() { + return Err(DescriptorError::MissingFileName); + } + files.push(( + name, + File { + bytes, + descriptor: Some(descriptor), + }, + )); + } + let mut inner = self.inner.write(); + inner.files.extend(files); + inner.reindex(); + Ok(()) + } + /// Registers a fully-qualified service name such as `helloworld.Greeter`. pub fn add_service(&self, name: impl Into) { - self.services.write().push(name.into()); + self.inner.write().services.insert(name.into()); } - /// Registers a serialized `FileDescriptorProto`, replacing one under the same filename. + /// Stores a serialized `FileDescriptorProto`, replacing the same filename and its index. + /// Prefer `register_encoded_file_descriptor_set` to validate descriptors before serving. pub fn add_file(&self, filename: impl Into, descriptor: Vec) { - self.files.upsert_sync(filename.into(), descriptor); + let mut inner = self.inner.write(); + inner.files.insert(filename.into(), File::new(descriptor)); + inner.reindex(); } - /// Maps a symbol such as `pkg.Service.Method` to its file, replacing an earlier mapping. + /// Maps a symbol to its file, overriding the automatically indexed mapping. pub fn map_symbol(&self, symbol: impl Into, filename: impl Into) { - self.symbols.upsert_sync(symbol.into(), filename.into()); + self + .inner + .write() + .symbols + .insert(symbol.into(), filename.into()); } + /// Sorted, deduplicated names from descriptors and `add_service`. pub fn list_services(&self) -> Vec { - self.services.read().clone() + self.inner.read().services() } pub fn file_by_filename(&self, filename: &str) -> Option> { - self.files.get_sync(filename).map(|e| e.get().clone()) + self + .inner + .read() + .files + .get(filename) + .map(|file| file.bytes.clone()) } - /// Resolves the file a symbol was mapped to with [`map_symbol`](Self::map_symbol). + /// Resolves an indexed symbol or an explicit `map_symbol` mapping. pub fn file_containing_symbol(&self, symbol: &str) -> Option> { - let entry = self.symbols.get_sync(symbol)?; - let filename = entry.get().clone(); - drop(entry); - self.file_by_filename(&filename) + let inner = self.inner.read(); + let filename = inner.filename_for_symbol(symbol)?; + inner.files.get(filename).map(|file| file.bytes.clone()) + } + + fn respond(&self, request: ServerReflectionRequest) -> ServerReflectionResponse { + let answer = self + .answer(request.message_request.as_ref()) + .unwrap_or_else(MessageResponse::ErrorResponse); + ServerReflectionResponse { + valid_host: request.host.clone(), + original_request: Some(request), + message_response: Some(answer), + } + } + + fn answer(&self, request: Option<&MessageRequest>) -> Result { + let inner = self.inner.read(); + let filename = match request { + Some(MessageRequest::ListServices(_)) => { + return Ok(MessageResponse::ListServicesResponse(ListServiceResponse { + service: inner + .services() + .into_iter() + .map(|name| ServiceResponse { name }) + .collect(), + })); + } + Some(MessageRequest::FileByFilename(filename)) => filename, + Some(MessageRequest::FileContainingSymbol(symbol)) => { + inner.filename_for_symbol(symbol).ok_or_else(|| { + error( + GrpcStatusCode::NotFound, + format!("symbol not found: {symbol}"), + ) + })? + } + Some(MessageRequest::FileContainingExtension(extension)) => inner + .index + .extensions + .get(&extension.containing_type) + .and_then(|extensions| extensions.get(&extension.extension_number)) + .ok_or_else(|| error(GrpcStatusCode::NotFound, "extension not found"))?, + Some(MessageRequest::AllExtensionNumbersOfType(name)) => { + if !inner.index.messages.contains(name) { + return Err(error( + GrpcStatusCode::NotFound, + format!("message type not found: {name}"), + )); + } + return Ok(MessageResponse::AllExtensionNumbersResponse( + ExtensionNumberResponse { + base_type_name: name.clone(), + extension_number: inner + .index + .extensions + .get(name) + .map(|extensions| extensions.keys().copied().collect()) + .unwrap_or_default(), + }, + )); + } + None => { + return Err(error( + GrpcStatusCode::InvalidArgument, + "missing reflection query", + )); + } + }; + Ok(MessageResponse::FileDescriptorResponse( + FileDescriptorResponse { + file_descriptor_proto: inner.with_dependencies(filename)?, + }, + )) } } @@ -55,3 +213,10 @@ impl ReflectionRegistry { pub struct ReflectionState { pub registry: ReflectionRegistry, } + +// Retaining the embedded bytes preserves custom options that prost-types does not recognize. +#[derive(prost::Message)] +struct EncodedDescriptorSet { + #[prost(bytes = "vec", repeated, tag = "1")] + files: Vec>, +} diff --git a/tako-rs-core/src/grpc/reflection/descriptors.rs b/tako-rs-core/src/grpc/reflection/descriptors.rs new file mode 100644 index 00000000..b5584bc2 --- /dev/null +++ b/tako-rs-core/src/grpc/reflection/descriptors.rs @@ -0,0 +1,165 @@ +use std::collections::BTreeMap; +use std::collections::BTreeSet; + +use prost::Message; +use prost_types::DescriptorProto; +use prost_types::EnumDescriptorProto; +use prost_types::FieldDescriptorProto; +use prost_types::FileDescriptorProto; + +use super::ErrorResponse; +use crate::grpc::GrpcStatusCode; + +pub(super) struct File { + pub bytes: Vec, + pub descriptor: Option, +} + +impl File { + pub fn new(bytes: Vec) -> Self { + let descriptor = FileDescriptorProto::decode(bytes.as_slice()).ok(); + Self { bytes, descriptor } + } +} + +#[derive(Default)] +pub(super) struct Descriptors { + pub files: BTreeMap, + pub services: BTreeSet, + pub symbols: BTreeMap, + pub index: Index, +} + +impl Descriptors { + pub fn reindex(&mut self) { + let mut index = Index::default(); + for (filename, file) in &self.files { + if let Some(descriptor) = &file.descriptor { + index.insert(filename, descriptor); + } + } + self.index = index; + } + + pub fn services(&self) -> Vec { + self.services.union(&self.index.services).cloned().collect() + } + + pub fn filename_for_symbol(&self, symbol: &str) -> Option<&str> { + self + .symbols + .get(symbol) + .or_else(|| self.index.symbols.get(symbol)) + .map(String::as_str) + } + + pub fn with_dependencies(&self, filename: &str) -> Result>, ErrorResponse> { + let mut pending = vec![filename]; + let mut visited = BTreeSet::new(); + let mut descriptors = Vec::new(); + while let Some(filename) = pending.pop() { + if !visited.insert(filename) { + continue; + } + let file = self.files.get(filename).ok_or_else(|| { + error( + GrpcStatusCode::NotFound, + format!("file not found: {filename}"), + ) + })?; + let descriptor = file.descriptor.as_ref().ok_or_else(|| { + error( + GrpcStatusCode::Internal, + format!("invalid descriptor: {filename}"), + ) + })?; + descriptors.push(file.bytes.clone()); + pending.extend(descriptor.dependency.iter().rev().map(String::as_str)); + } + Ok(descriptors) + } +} + +#[derive(Default)] +pub(super) struct Index { + pub services: BTreeSet, + pub symbols: BTreeMap, + pub messages: BTreeSet, + pub extensions: BTreeMap>, +} + +impl Index { + fn insert(&mut self, filename: &str, file: &FileDescriptorProto) { + let package = file.package(); + for service in &file.service { + let name = self.symbol(package, service.name(), filename); + self.services.insert(name.clone()); + for method in &service.method { + self.symbol(&name, method.name(), filename); + } + } + for message in &file.message_type { + self.message(package, message, filename); + } + for enumeration in &file.enum_type { + self.enumeration(package, enumeration, filename); + } + for extension in &file.extension { + self.extension(package, extension, filename); + } + } + + fn symbol(&mut self, prefix: &str, name: &str, filename: &str) -> String { + let name = if prefix.is_empty() { + name.to_owned() + } else { + format!("{prefix}.{name}") + }; + self.symbols.insert(name.clone(), filename.to_owned()); + name + } + + fn message(&mut self, prefix: &str, message: &DescriptorProto, filename: &str) { + let name = self.symbol(prefix, message.name(), filename); + self.messages.insert(name.clone()); + for field in &message.field { + self.symbol(&name, field.name(), filename); + } + for oneof in &message.oneof_decl { + self.symbol(&name, oneof.name(), filename); + } + for nested in &message.nested_type { + self.message(&name, nested, filename); + } + for enumeration in &message.enum_type { + self.enumeration(&name, enumeration, filename); + } + for extension in &message.extension { + self.extension(&name, extension, filename); + } + } + + fn enumeration(&mut self, prefix: &str, enumeration: &EnumDescriptorProto, filename: &str) { + self.symbol(prefix, enumeration.name(), filename); + for value in &enumeration.value { + // Protobuf enum values occupy the enclosing scope, unlike Rust variants. + self.symbol(prefix, value.name(), filename); + } + } + + fn extension(&mut self, prefix: &str, extension: &FieldDescriptorProto, filename: &str) { + self.symbol(prefix, extension.name(), filename); + self + .extensions + .entry(extension.extendee().trim_start_matches('.').to_owned()) + .or_default() + .insert(extension.number(), filename.to_owned()); + } +} + +pub(super) fn error(code: GrpcStatusCode, message: impl Into) -> ErrorResponse { + ErrorResponse { + error_code: code as i32, + error_message: message.into(), + } +} diff --git a/tako-rs-core/src/grpc/reflection/error.rs b/tako-rs-core/src/grpc/reflection/error.rs new file mode 100644 index 00000000..80cef0a1 --- /dev/null +++ b/tako-rs-core/src/grpc/reflection/error.rs @@ -0,0 +1,31 @@ +use std::fmt; + +#[derive(Debug)] +pub enum DescriptorError { + Decode(prost::DecodeError), + MissingFileName, +} + +impl fmt::Display for DescriptorError { + fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + Self::Decode(error) => error.fmt(formatter), + Self::MissingFileName => formatter.write_str("file descriptor has no name"), + } + } +} + +impl std::error::Error for DescriptorError { + fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { + match self { + Self::Decode(error) => Some(error), + Self::MissingFileName => None, + } + } +} + +impl From for DescriptorError { + fn from(error: prost::DecodeError) -> Self { + Self::Decode(error) + } +} diff --git a/tako-rs-core/src/grpc/reflection/protocol.rs b/tako-rs-core/src/grpc/reflection/protocol.rs new file mode 100644 index 00000000..60240072 --- /dev/null +++ b/tako-rs-core/src/grpc/reflection/protocol.rs @@ -0,0 +1,101 @@ +//! Wire-compatible messages shared by the v1 and v1alpha reflection protocols. + +#[derive(Clone, PartialEq, prost::Message)] +pub struct ServerReflectionRequest { + #[prost(string, tag = "1")] + pub host: String, + #[prost( + oneof = "server_reflection_request::MessageRequest", + tags = "3, 4, 5, 6, 7" + )] + pub message_request: Option, +} + +pub mod server_reflection_request { + #[derive(Clone, PartialEq, prost::Oneof)] + pub enum MessageRequest { + #[prost(string, tag = "3")] + FileByFilename(String), + #[prost(string, tag = "4")] + FileContainingSymbol(String), + #[prost(message, tag = "5")] + FileContainingExtension(super::ExtensionRequest), + #[prost(string, tag = "6")] + AllExtensionNumbersOfType(String), + #[prost(string, tag = "7")] + ListServices(String), + } +} + +#[derive(Clone, PartialEq, prost::Message)] +pub struct ExtensionRequest { + #[prost(string, tag = "1")] + pub containing_type: String, + #[prost(int32, tag = "2")] + pub extension_number: i32, +} + +/// One response per query; query errors do not end the bidirectional stream. +#[derive(Clone, PartialEq, prost::Message)] +pub struct ServerReflectionResponse { + #[prost(string, tag = "1")] + pub valid_host: String, + #[prost(message, optional, tag = "2")] + pub original_request: Option, + #[prost( + oneof = "server_reflection_response::MessageResponse", + tags = "4, 5, 6, 7" + )] + pub message_response: Option, +} + +pub mod server_reflection_response { + #[derive(Clone, PartialEq, prost::Oneof)] + pub enum MessageResponse { + #[prost(message, tag = "4")] + FileDescriptorResponse(super::FileDescriptorResponse), + #[prost(message, tag = "5")] + AllExtensionNumbersResponse(super::ExtensionNumberResponse), + #[prost(message, tag = "6")] + ListServicesResponse(super::ListServiceResponse), + #[prost(message, tag = "7")] + ErrorResponse(super::ErrorResponse), + } +} + +/// Serialized `FileDescriptorProto` values, including transitive dependencies. +#[derive(Clone, PartialEq, prost::Message)] +pub struct FileDescriptorResponse { + #[prost(bytes = "vec", repeated, tag = "1")] + pub file_descriptor_proto: Vec>, +} + +#[derive(Clone, PartialEq, prost::Message)] +pub struct ExtensionNumberResponse { + #[prost(string, tag = "1")] + pub base_type_name: String, + #[prost(int32, repeated, tag = "2")] + pub extension_number: Vec, +} + +#[derive(Clone, PartialEq, prost::Message)] +pub struct ListServiceResponse { + #[prost(message, repeated, tag = "1")] + pub service: Vec, +} + +/// Fully-qualified protobuf service name. +#[derive(Clone, PartialEq, prost::Message)] +pub struct ServiceResponse { + #[prost(string, tag = "1")] + pub name: String, +} + +/// Query error, using the numeric gRPC status codes. +#[derive(Clone, PartialEq, prost::Message)] +pub struct ErrorResponse { + #[prost(int32, tag = "1")] + pub error_code: i32, + #[prost(string, tag = "2")] + pub error_message: String, +} diff --git a/tako-rs-core/tests/grpc_registry.rs b/tako-rs-core/tests/grpc_registry.rs new file mode 100644 index 00000000..13c4c7ec --- /dev/null +++ b/tako-rs-core/tests/grpc_registry.rs @@ -0,0 +1,86 @@ +#![cfg(feature = "grpc")] + +use futures_util::StreamExt; +use prost::Message; +use prost_types::FileDescriptorProto; +use prost_types::ServiceDescriptorProto; +use tako::body::TakoBody; +use tako::grpc::health::HealthRegistry; +use tako::grpc::health::ServingStatus; +use tako::grpc::reflection::ReflectionRegistry; +use tako::router::Router; + +#[test] +fn descriptor_sets_preserve_unknown_custom_options() { + let registry = ReflectionRegistry::new(); + let file = b"\x0a\x07a.proto\x42\x03\xa0\x06\x07"; + let set = [b"\x0a\x0e".as_slice(), file].concat(); + registry.register_encoded_file_descriptor_set(&set).unwrap(); + assert_eq!(registry.file_by_filename("a.proto").unwrap(), file); +} + +#[test] +fn invalid_descriptor_sets_do_not_partially_update_the_registry() { + for invalid in [b"\x0a\x00".as_slice(), b"\x0a\xff".as_slice()] { + let registry = ReflectionRegistry::new(); + let bytes = [b"\x0a\x09\x0a\x07a.proto".as_slice(), invalid].concat(); + assert!( + registry + .register_encoded_file_descriptor_set(&bytes) + .is_err() + ); + assert!(registry.file_by_filename("a.proto").is_none()); + } +} + +#[test] +fn replacing_a_file_removes_its_stale_symbols_and_services() { + let registry = ReflectionRegistry::new(); + for name in ["Old", "New"] { + let file = FileDescriptorProto { + name: Some("api.proto".into()), + package: Some("test".into()), + service: vec![ServiceDescriptorProto { + name: Some(name.into()), + ..Default::default() + }], + ..Default::default() + }; + registry.clone().add_file("api.proto", file.encode_to_vec()); + } + assert_eq!(registry.list_services(), ["test.New"]); + assert!(registry.file_containing_symbol("test.Old").is_none()); + assert!(registry.file_containing_symbol("test.New").is_some()); + registry.map_symbol("alias", "api.proto"); + assert!(registry.file_containing_symbol("alias").is_some()); +} + +#[tokio::test] +async fn watching_unknown_services_does_not_register_them() { + let registry = HealthRegistry::new(); + let mut watch = Box::pin(registry.watch("unknown")); + assert_eq!(watch.next().await.unwrap().unwrap().status, 3); + assert_eq!(registry.snapshot().len(), 0); + registry.set_status("unknown", ServingStatus::Serving); + assert_eq!(watch.next().await.unwrap().unwrap().status, 1); +} + +#[cfg_attr(feature = "compio", compio::test)] +#[cfg_attr(not(feature = "compio"), tokio::test)] +async fn health_list_rejects_expired_deadlines() { + let registry = HealthRegistry::new(); + registry.set_status("", ServingStatus::Serving); + let mut router = Router::new(); + registry.register(&mut router); + let request = http::Request::builder() + .method("POST") + .uri("/grpc.health.v1.Health/List") + .header("content-type", "application/grpc") + .header("grpc-timeout", "0n") + .body(TakoBody::from(vec![0; 5])) + .unwrap(); + + let response = router.dispatch(request).await; + + assert_eq!(response.headers().get("grpc-status").unwrap(), "4"); +} diff --git a/tako-rs/Cargo.toml b/tako-rs/Cargo.toml index 1f265c8e..6b1ce5bf 100644 --- a/tako-rs/Cargo.toml +++ b/tako-rs/Cargo.toml @@ -109,6 +109,7 @@ futures-util = { workspace = true } http = { workspace = true } http-body-util = { workspace = true } prost = { workspace = true } +prost-types = { workspace = true } serde = { workspace = true } serde_json = { workspace = true } smallvec = { workspace = true } diff --git a/tako-rs/tests/grpc_services.rs b/tako-rs/tests/grpc_services.rs new file mode 100644 index 00000000..77cae9c0 --- /dev/null +++ b/tako-rs/tests/grpc_services.rs @@ -0,0 +1,98 @@ +#![cfg(all(feature = "grpc", feature = "http2"))] + +//! Standard services exercised through independent protobuf messages and a tonic client. + +use std::net::SocketAddr; +use std::sync::Arc; +use std::sync::atomic::AtomicUsize; +use std::time::Duration; + +use tako::grpc::health::HealthRegistry; +use tako::grpc::health::ServingStatus; +use tako::router::Router; +use tonic::transport::Channel; + +#[path = "grpc_services/cancellation.rs"] +mod cancellation; +#[path = "grpc_services/health.rs"] +mod health; +#[path = "grpc_services/reflection.rs"] +mod reflection; +#[path = "grpc_services/wire.rs"] +mod wire; + +async fn client(address: SocketAddr) -> tonic::client::Grpc { + let channel = tonic::transport::Endpoint::from_shared(format!("http://{address}")) + .unwrap() + .connect() + .await + .unwrap(); + tonic::client::Grpc::new(channel) +} + +fn router(health: &HealthRegistry, dropped: &Arc) -> Router { + let mut router = Router::new(); + cancellation::monitor(&router, dropped); + health.set_status("", ServingStatus::Serving); + health.register(&mut router); + reflection::registry().register(&mut router); + router +} + +async fn exercise(address: SocketAddr, health: HealthRegistry, dropped: Arc) { + health::check(address, &health).await; + health::watch(address, &health, &dropped).await; + health::deadline(address).await; + reflection::lookups(address).await; + reflection::errors(address).await; + reflection::alpha(address).await; +} + +#[cfg(not(feature = "compio"))] +#[tokio::test] +async fn standard_grpc_services_on_tokio() { + let health = HealthRegistry::new(); + let dropped = Arc::new(AtomicUsize::new(0)); + let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap(); + let address = listener.local_addr().unwrap(); + let handle = tako::Server::builder() + .build() + .try_spawn_h2c(listener, router(&health, &dropped)) + .unwrap(); + tokio::time::timeout(Duration::from_secs(15), exercise(address, health, dropped)) + .await + .expect("standard gRPC services timed out"); + handle.shutdown(Duration::from_secs(1)).await; +} + +#[cfg(feature = "compio")] +#[test] +fn standard_grpc_services_on_compio() { + compio::runtime::Runtime::new().unwrap().block_on(async { + let health = HealthRegistry::new(); + let dropped = Arc::new(AtomicUsize::new(0)); + let listener = compio::net::TcpListener::bind("127.0.0.1:0").await.unwrap(); + let address = listener.local_addr().unwrap(); + let handle = tako::CompioServer::builder() + .build() + .try_spawn_h2c(listener, router(&health, &dropped)) + .unwrap(); + let (done, finished) = tokio::sync::oneshot::channel(); + let client = std::thread::spawn(move || { + tokio::runtime::Builder::new_current_thread() + .enable_all() + .build() + .unwrap() + .block_on(exercise(address, health, dropped)); + let _ = done.send(()); + }); + compio::time::timeout(Duration::from_secs(15), finished) + .await + .expect("standard gRPC services timed out") + .ok(); + if let Err(panic) = client.join() { + std::panic::resume_unwind(panic); + } + handle.shutdown(Duration::from_secs(1)).await; + }); +} diff --git a/tako-rs/tests/grpc_services/cancellation.rs b/tako-rs/tests/grpc_services/cancellation.rs new file mode 100644 index 00000000..aa9176d2 --- /dev/null +++ b/tako-rs/tests/grpc_services/cancellation.rs @@ -0,0 +1,47 @@ +use std::sync::Arc; +use std::sync::atomic::AtomicUsize; +use std::sync::atomic::Ordering; +use std::time::Duration; + +use http_body_util::BodyExt; +use tako::body::TakoBody; +use tako::middleware::Next; +use tako::router::Router; +use tako::types::Request; + +struct DropCounter(Arc); + +impl Drop for DropCounter { + fn drop(&mut self) { + self.0.fetch_add(1, Ordering::SeqCst); + } +} + +pub fn monitor(router: &Router, dropped: &Arc) { + let dropped = dropped.clone(); + router.middleware(move |request: Request, next: Next| { + let watch = request.uri().path() == "/grpc.health.v1.Health/Watch"; + let dropped = dropped.clone(); + async move { + let mut response = next.run(request).await; + if watch { + let body = std::mem::take(response.body_mut()); + let stream = futures_util::stream::unfold((body, DropCounter(dropped)), |(mut body, counter)| async move { + body.frame().await.map(|frame| (frame, (body, counter))) + }); + *response.body_mut() = TakoBody::from_try_stream(stream); + } + response + } + }); +} + +pub async fn wait(dropped: &AtomicUsize, previous: usize) { + tokio::time::timeout(Duration::from_secs(2), async { + while dropped.load(Ordering::SeqCst) == previous { + tokio::time::sleep(Duration::from_millis(5)).await; + } + }) + .await + .expect("the server retained a cancelled health watch"); +} diff --git a/tako-rs/tests/grpc_services/health.rs b/tako-rs/tests/grpc_services/health.rs new file mode 100644 index 00000000..0715863a --- /dev/null +++ b/tako-rs/tests/grpc_services/health.rs @@ -0,0 +1,117 @@ +use std::net::SocketAddr; +use std::sync::atomic::AtomicUsize; +use std::sync::atomic::Ordering; +use std::time::Duration; + +use tako::grpc::health::HealthRegistry; +use tako::grpc::health::ServingStatus; +use tonic::Code; +use tonic_prost::ProstCodec; + +use super::client; +use super::wire::HealthListRequest; +use super::wire::HealthListResponse; +use super::wire::HealthRequest; +use super::wire::HealthResponse; + +fn request(service: &str) -> tonic::Request { + tonic::Request::new(HealthRequest { + service: service.into(), + }) +} + +pub async fn check(address: SocketAddr, registry: &HealthRegistry) { + let mut grpc = client(address).await; + let codec = ProstCodec::::new; + for (service, expected) in [("", Ok(1)), ("missing", Err(Code::NotFound))] { + grpc.ready().await.unwrap(); + let response = grpc + .unary( + request(service), + "/grpc.health.v1.Health/Check".parse().unwrap(), + codec(), + ) + .await + .map(|response| response.into_inner().status) + .map_err(|status| status.code()); + assert_eq!(response, expected); + } + registry.clone().set_status("", ServingStatus::NotServing); + grpc.ready().await.unwrap(); + let response = grpc + .unary( + request(""), + "/grpc.health.v1.Health/Check".parse().unwrap(), + codec(), + ) + .await + .unwrap(); + assert_eq!(response.into_inner().status, 2); + grpc.ready().await.unwrap(); + let response = grpc + .unary( + tonic::Request::new(HealthListRequest {}), + "/grpc.health.v1.Health/List".parse().unwrap(), + ProstCodec::::new(), + ) + .await + .unwrap() + .into_inner(); + assert_eq!(response.statuses.len(), 1); + assert_eq!(response.statuses[""].status, 2); +} + +pub async fn watch(address: SocketAddr, registry: &HealthRegistry, dropped: &AtomicUsize) { + let mut grpc = client(address).await; + grpc.ready().await.unwrap(); + let mut watch = grpc + .server_streaming( + request("later"), + "/grpc.health.v1.Health/Watch".parse().unwrap(), + ProstCodec::::new(), + ) + .await + .unwrap() + .into_inner(); + assert_eq!(watch.message().await.unwrap().unwrap().status, 3); + for (status, code) in [ + (ServingStatus::Serving, 1), + (ServingStatus::NotServing, 2), + (ServingStatus::Unknown, 0), + ] { + registry.set_status("later", status); + assert_eq!(watch.message().await.unwrap().unwrap().status, code); + } + registry.set_status("later", ServingStatus::Unknown); + registry.set_status("unrelated", ServingStatus::Serving); + assert!( + tokio::time::timeout(Duration::from_millis(50), watch.message()) + .await + .is_err() + ); + let previous = dropped.load(Ordering::SeqCst); + drop(watch); + super::cancellation::wait(dropped, previous).await; + registry.set_status("later", ServingStatus::Serving); +} + +pub async fn deadline(address: SocketAddr) { + let mut grpc = client(address).await; + let mut request = request("never"); + request.set_timeout(Duration::from_millis(80)); + grpc.ready().await.unwrap(); + let mut watch = grpc + .server_streaming( + request, + "/grpc.health.v1.Health/Watch".parse().unwrap(), + ProstCodec::::new(), + ) + .await + .unwrap() + .into_inner(); + assert_eq!(watch.message().await.unwrap().unwrap().status, 3); + assert_eq!( + watch.message().await.unwrap_err().code(), + Code::DeadlineExceeded + ); +} diff --git a/tako-rs/tests/grpc_services/proto/service.proto b/tako-rs/tests/grpc_services/proto/service.proto new file mode 100644 index 00000000..32971d41 --- /dev/null +++ b/tako-rs/tests/grpc_services/proto/service.proto @@ -0,0 +1,15 @@ +syntax = "proto2"; +package test; +import "shared.proto"; + +message Input { + optional shared.Container.Nested input = 1; +} + +service Math { + rpc Count(Input) returns (shared.Container.Nested); +} + +extend shared.Container { + optional string note = 100; +} diff --git a/tako-rs/tests/grpc_services/proto/services.bin b/tako-rs/tests/grpc_services/proto/services.bin new file mode 100644 index 00000000..98513206 Binary files /dev/null and b/tako-rs/tests/grpc_services/proto/services.bin differ diff --git a/tako-rs/tests/grpc_services/proto/shared.proto b/tako-rs/tests/grpc_services/proto/shared.proto new file mode 100644 index 00000000..40896592 --- /dev/null +++ b/tako-rs/tests/grpc_services/proto/shared.proto @@ -0,0 +1,15 @@ +syntax = "proto2"; +package shared; + +message Container { + extensions 100 to 199; + message Nested { + optional int32 value = 1; + } + enum Mode { + ZERO = 0; + } + oneof selection { + int32 value = 1; + } +} diff --git a/tako-rs/tests/grpc_services/reflection.rs b/tako-rs/tests/grpc_services/reflection.rs new file mode 100644 index 00000000..a4f9bd95 --- /dev/null +++ b/tako-rs/tests/grpc_services/reflection.rs @@ -0,0 +1,221 @@ +use std::net::SocketAddr; +use std::time::Duration; + +use prost::Message; +use prost_types::FileDescriptorProto; +use tako::grpc::reflection::ReflectionRegistry; +use tonic_prost::ProstCodec; + +use super::client; +use super::wire::*; + +pub fn registry() -> ReflectionRegistry { + let registry = ReflectionRegistry::new(); + registry + .register_encoded_file_descriptor_set(include_bytes!("proto/services.bin")) + .unwrap(); + registry.add_service("test.Math"); + registry.map_symbol("legacy.Alias", "service.proto"); + registry.add_file( + "broken.proto", + FileDescriptorProto { + name: Some("broken.proto".into()), + dependency: vec!["absent.proto".into()], + ..Default::default() + } + .encode_to_vec(), + ); + registry.add_file("corrupt.proto", vec![0xff]); + registry +} + +async fn stream( + address: SocketAddr, + version: &str, +) -> ( + tokio::sync::mpsc::Sender, + tonic::Streaming, +) { + let mut grpc = client(address).await; + let (sender, mut receiver) = tokio::sync::mpsc::channel(1); + let outbound = futures_util::stream::poll_fn(move |cx| receiver.poll_recv(cx)); + grpc.ready().await.unwrap(); + let response = grpc + .streaming( + tonic::Request::new(outbound), + format!("/grpc.reflection.{version}.ServerReflection/ServerReflectionInfo") + .parse() + .unwrap(), + ProstCodec::::new(), + ) + .await + .unwrap() + .into_inner(); + (sender, response) +} + +async fn query( + sender: &tokio::sync::mpsc::Sender, + replies: &mut tonic::Streaming, + query: Option, +) -> Answer { + let request = ReflectionRequest { + host: "example.test".into(), + query, + }; + sender.send(request.clone()).await.unwrap(); + let reply = tokio::time::timeout(Duration::from_secs(2), replies.message()) + .await + .expect("reflection waited for the request stream to close") + .unwrap() + .unwrap(); + assert_eq!(reply.valid_host, "example.test"); + assert_eq!(reply.original_request, Some(request)); + reply.answer.unwrap() +} + +fn filenames(answer: Answer) -> Vec { + let Answer::Files(files) = answer else { + panic!("expected file descriptors: {answer:?}") + }; + let mut names = files + .descriptors + .iter() + .map(|file| { + FileDescriptorProto::decode(file.as_slice()) + .unwrap() + .name + .unwrap() + }) + .collect::>(); + names.sort(); + names +} + +pub async fn lookups(address: SocketAddr) { + let (sender, mut replies) = stream(address, "v1").await; + let Answer::Services(services) = + query(&sender, &mut replies, Some(Query::Services(String::new()))).await + else { + panic!("expected service list") + }; + let names = services + .services + .into_iter() + .map(|s| s.name) + .collect::>(); + assert_eq!( + names, + [ + "grpc.reflection.v1.ServerReflection", + "grpc.reflection.v1alpha.ServerReflection", + "test.Math" + ] + ); + for request in [ + Query::Filename("service.proto".into()), + Query::Symbol("test.Math".into()), + Query::Symbol("test.Math.Count".into()), + Query::Symbol("test.Input.input".into()), + Query::Symbol("test.note".into()), + Query::Symbol("legacy.Alias".into()), + Query::Extension(Extension { + containing_type: "shared.Container".into(), + number: 100, + }), + ] { + assert_eq!( + filenames(query(&sender, &mut replies, Some(request)).await), + ["service.proto", "shared.proto"] + ); + } + for symbol in [ + "shared.Container.Nested", + "shared.Container.Nested.value", + "shared.Container.Mode", + "shared.Container.ZERO", + "shared.Container.selection", + ] { + assert_eq!( + filenames(query(&sender, &mut replies, Some(Query::Symbol(symbol.into()))).await), + ["shared.proto"] + ); + } + for (name, expected) in [ + ("shared.Container", vec![100]), + ("shared.Container.Nested", vec![]), + ] { + let Answer::ExtensionNumbers(numbers) = query( + &sender, + &mut replies, + Some(Query::ExtensionNumbers(name.into())), + ) + .await + else { + panic!("expected extension numbers") + }; + assert_eq!(numbers.base_type_name, name); + assert_eq!(numbers.numbers, expected); + } + assert_eq!( + filenames( + query( + &sender, + &mut replies, + Some(Query::Symbol("grpc.reflection.v1.ServerReflection".into())) + ) + .await + ), + ["grpc/reflection/v1/reflection.proto"] + ); + drop(sender); + assert!(replies.message().await.unwrap().is_none()); +} + +pub async fn errors(address: SocketAddr) { + let (sender, mut replies) = stream(address, "v1").await; + for (request, code) in [ + (None, 3), + (Some(Query::Filename("missing.proto".into())), 5), + (Some(Query::Filename("broken.proto".into())), 5), + (Some(Query::Filename("corrupt.proto".into())), 13), + (Some(Query::Symbol("missing.Service".into())), 5), + ( + Some(Query::Extension(Extension { + containing_type: "shared.Container".into(), + number: 101, + })), + 5, + ), + (Some(Query::ExtensionNumbers("missing.Type".into())), 5), + ] { + let Answer::Error(error) = query(&sender, &mut replies, request).await else { + panic!("expected error response") + }; + assert_eq!(error.code, code); + assert_ne!(error.message, ""); + } + assert!(matches!( + query(&sender, &mut replies, Some(Query::Services(String::new()))).await, + Answer::Services(_) + )); + drop(sender); + assert!(replies.message().await.unwrap().is_none()); +} + +pub async fn alpha(address: SocketAddr) { + let (sender, mut replies) = stream(address, "v1alpha").await; + assert_eq!( + filenames( + query( + &sender, + &mut replies, + Some(Query::Symbol("test.Math".into())) + ) + .await + ), + ["service.proto", "shared.proto"] + ); + drop(sender); + assert!(replies.message().await.unwrap().is_none()); +} diff --git a/tako-rs/tests/grpc_services/wire.rs b/tako-rs/tests/grpc_services/wire.rs new file mode 100644 index 00000000..fa16e1fa --- /dev/null +++ b/tako-rs/tests/grpc_services/wire.rs @@ -0,0 +1,108 @@ +use prost::Message; + +#[derive(Clone, PartialEq, Message)] +pub struct HealthRequest { + #[prost(string, tag = "1")] + pub service: String, +} + +#[derive(Clone, Copy, PartialEq, Message)] +pub struct HealthResponse { + #[prost(int32, tag = "1")] + pub status: i32, +} + +#[derive(Clone, Copy, PartialEq, Message)] +pub struct HealthListRequest {} + +#[derive(Clone, PartialEq, Message)] +pub struct HealthListResponse { + #[prost(btree_map = "string, message", tag = "1")] + pub statuses: std::collections::BTreeMap, +} + +#[derive(Clone, PartialEq, Message)] +pub struct ReflectionRequest { + #[prost(string, tag = "1")] + pub host: String, + #[prost(oneof = "Query", tags = "3, 4, 5, 6, 7")] + pub query: Option, +} + +#[derive(Clone, PartialEq, prost::Oneof)] +pub enum Query { + #[prost(string, tag = "3")] + Filename(String), + #[prost(string, tag = "4")] + Symbol(String), + #[prost(message, tag = "5")] + Extension(Extension), + #[prost(string, tag = "6")] + ExtensionNumbers(String), + #[prost(string, tag = "7")] + Services(String), +} + +#[derive(Clone, PartialEq, Message)] +pub struct Extension { + #[prost(string, tag = "1")] + pub containing_type: String, + #[prost(int32, tag = "2")] + pub number: i32, +} + +#[derive(Clone, PartialEq, Message)] +pub struct ReflectionResponse { + #[prost(string, tag = "1")] + pub valid_host: String, + #[prost(message, optional, tag = "2")] + pub original_request: Option, + #[prost(oneof = "Answer", tags = "4, 5, 6, 7")] + pub answer: Option, +} + +#[derive(Clone, PartialEq, prost::Oneof)] +pub enum Answer { + #[prost(message, tag = "4")] + Files(Files), + #[prost(message, tag = "5")] + ExtensionNumbers(ExtensionNumbers), + #[prost(message, tag = "6")] + Services(Services), + #[prost(message, tag = "7")] + Error(Error), +} + +#[derive(Clone, PartialEq, Message)] +pub struct Files { + #[prost(bytes = "vec", repeated, tag = "1")] + pub descriptors: Vec>, +} + +#[derive(Clone, PartialEq, Message)] +pub struct ExtensionNumbers { + #[prost(string, tag = "1")] + pub base_type_name: String, + #[prost(int32, repeated, tag = "2")] + pub numbers: Vec, +} + +#[derive(Clone, PartialEq, Message)] +pub struct Services { + #[prost(message, repeated, tag = "1")] + pub services: Vec, +} + +#[derive(Clone, PartialEq, Message)] +pub struct Service { + #[prost(string, tag = "1")] + pub name: String, +} + +#[derive(Clone, PartialEq, Message)] +pub struct Error { + #[prost(int32, tag = "1")] + pub code: i32, + #[prost(string, tag = "2")] + pub message: String, +} diff --git a/website/content/docs/reference/migration.mdx b/website/content/docs/reference/migration.mdx index d980fb2c..e6e0cd15 100644 --- a/website/content/docs/reference/migration.mdx +++ b/website/content/docs/reference/migration.mdx @@ -326,8 +326,10 @@ matching thread-safe equivalent. The `per-thread-local` / `GrpcDeadline(Instant)` extension. - `GrpcInterceptor` async trait + `InterceptorChain` short-circuiting on the first `Err(GrpcStatus)`. -- Reflection / health scaffolding (storage layer ships now; protobuf - encoders deferred until consumers don't have to ship `protoc`). +- Standard health Check / Watch / List and bidirectional server reflection + are available through `HealthRegistry::register` and + `ReflectionRegistry::register`, with checked-in protobuf types and descriptors. + See [gRPC services](/docs/transports/grpc#health-checks). - gRPC-Web byte-level decoder/encoder helpers. ## 17. GraphQL & OpenAPI @@ -382,7 +384,6 @@ The following are tracked separately and have **not yet** landed: - `tako-stores-redis`, `tako-stores-postgres` - `TlsCert::Acme { ... }` - Multipart/byteranges responder, Linux `sendfile(2)` path -- Generated gRPC stubs (reflection / health protobuf) - Cluster `SignalBus` impls (Redis, NATS, Kafka) - Hot-reload `Arc` swap (current path keeps `Box::leak` for per-connection performance) diff --git a/website/content/docs/transports/grpc.mdx b/website/content/docs/transports/grpc.mdx index 6c1fddbc..af477611 100644 --- a/website/content/docs/transports/grpc.mdx +++ b/website/content/docs/transports/grpc.mdx @@ -6,7 +6,7 @@ since: 2.0.0 status: stable crate: tako-rs-core runtime: both -features: [grpc] +features: [grpc, http2] --- # gRPC @@ -318,9 +318,84 @@ Compressed messages are **not** supported. A request whose compressed-flag byte set is rejected with `Unimplemented`, signalling the client to retry uncompressed. +## Health checks + +`HealthRegistry::register` adds the standard `grpc.health.v1.Health` Check, +Watch, and List methods. The registry starts empty; set the empty service name +for the server's overall status and fully-qualified names for individual services: + +```rust +use tako::grpc::health::{HealthRegistry, ServingStatus}; +use tako::router::Router; + +let mut router = Router::new(); +let health = HealthRegistry::new(); +health.set_status("", ServingStatus::Serving); +health.set_status("numbers.Numbers", ServingStatus::Serving); +health.register(&mut router); + +// A clone can report readiness changes while the server is running. +let reporter = health.clone(); +reporter.set_status("numbers.Numbers", ServingStatus::NotServing); +``` + +Check returns `NotFound` for an unknown service. Watch immediately reports the +current status, using `ServiceUnknown` for an unknown name, and stays open for +updates. Repeating a status does not emit another message. Slow readers receive +the latest status without an unbounded backlog. Dropping the call releases its +subscription, and the client's `grpc-timeout` ends a watch with `DeadlineExceeded`. +List returns a snapshot of the registered services. + +## Server reflection + +`ReflectionRegistry::register` serves bidirectional reflection on both +`grpc.reflection.v1.ServerReflection` and the compatible `v1alpha` path used by +older clients. The standard messages and descriptors ship with Tako; consumer +builds do not need `protoc` for health or reflection. + +Create a descriptor set for your application, including imported definitions: + +```bash +protoc -I proto --include_imports --descriptor_set_out=proto/numbers.bin \ + proto/numbers.proto +``` + +Commit the descriptor alongside your generated messages, or produce it in your +existing protobuf build step. Register it on the same router as the RPC handlers: + +```rust +use tako::grpc::{health, reflection::ReflectionRegistry}; + +let reflection = ReflectionRegistry::new(); +reflection.register_encoded_file_descriptor_set(include_bytes!("../proto/numbers.bin"))?; +reflection.register_encoded_file_descriptor_set(health::FILE_DESCRIPTOR_SET)?; +reflection.register(&mut router); +``` + +Descriptor sets automatically index services, methods, messages, nested types, +fields, enums, and extensions. File and symbol lookups return the requested +descriptor plus its transitive imports. Custom protobuf options are preserved. +The registry also retains `add_service`, `add_file`, and `map_symbol` for manual +registration; importing a descriptor set validates it before changing the registry. +Service lists are sorted and deduplicated. + +Missing files, symbols, or extensions return `NotFound` in a reflection error +message; a query without a request returns `InvalidArgument`. These errors leave +the stream open for the next query. Include all imports when registering a set: +a missing dependency also produces `NotFound`. Reflection exposes registered +schemas through ordinary routes, so existing router middleware can control access. + ## Calling it with grpcurl -Tako has no server reflection, so pass the `.proto` file to the client: +With reflection registered, clients can discover schemas directly: + +```bash +grpcurl -plaintext 127.0.0.1:50051 list +grpcurl -plaintext -d '{"value": 3}' 127.0.0.1:50051 numbers.Numbers/Count +grpcurl -plaintext -d '{"service": ""}' 127.0.0.1:50051 grpc.health.v1.Health/Check +``` + +Without reflection, pass the `.proto` file to the client: ```bash grpcurl -plaintext -import-path proto -proto numbers.proto \ @@ -334,8 +409,8 @@ client on both runtimes. ## Other helpers -The module also contains a gRPC-Web bridge, a `GrpcInterceptor` chain, and -`grpc.health.v1` / reflection scaffolding. These are lower-level building blocks; +The module also contains a gRPC-Web bridge and a `GrpcInterceptor` chain. +These are lower-level building blocks; for browser-facing realtime, prefer [SSE](/docs/transports/sse) or [WebSocket](/docs/transports/websocket).