Crate ginepro

ginepro offers an enriched tonic Channel using a pluggable service discovery to periodcally update the active set of gRPC servers.

Simple example

#[tokio::main]
async fn main() {
    use ginepro::LoadBalancedChannel;
    use shared_proto::pb::tester_client::TesterClient;
    use std::convert::TryInto;

    // Create a load balanced channel with the default lookup implementation.
    let load_balanced_channel = LoadBalancedChannel::builder(("my.hostname", 5000))
        .channel()
        .await
        .expect("failed to construct LoadBalancedChannel");

    let tester_client = TesterClient::new(load_balanced_channel);
}

LoadBalancedChannel also allows plugging in a different implementation of LookupService.

use ginepro::{LookupService, ServiceDefinition};
use std::collections::HashSet;
use std::net::SocketAddr;

// This does nothing
struct DummyLookupService;

#[async_trait::async_trait]
impl LookupService for DummyLookupService {
    async fn resolve_service_endpoints(
        &self,
        _definition: &ServiceDefinition,
    ) -> Result<HashSet<SocketAddr>, anyhow::Error> {
        Ok(HashSet::new())
    }
}

#[tokio::main]
async fn main() {
    use ginepro::LoadBalancedChannel;
    use shared_proto::pb::tester_client::TesterClient;
    use std::convert::TryInto;

    // Create a load balanced channel with a dummy lookup implementation.
    let load_balanced_channel = LoadBalancedChannel::builder(("my.hostname", 5000))
        .lookup_service(DummyLookupService)
        .channel()
        .await
        .expect("failed to construct LoadBalancedChannel");

    let tester_client = TesterClient::new(load_balanced_channel);
}

For systems with higher churn, the probe interval can be lowered.

#[tokio::main]
async fn main() {
    use ginepro::{LoadBalancedChannel, LoadBalancedChannelBuilder};
    use shared_proto::pb::tester_client::TesterClient;
    use std::convert::TryInto;

    let load_balanced_channel = LoadBalancedChannelBuilder::new_with_service(("my.hostname", 5000))
        .dns_probe_interval(std::time::Duration::from_secs(3))
        .channel()
        .await
        .expect("failed to construct LoadBalancedChannel");

    let tester_client = TesterClient::new(load_balanced_channel);
}

It’s also possible to associate a timeout for every new endpoint that the LoadBalancedChannel tries to connect to. .

#[tokio::main]
async fn main() {
    use ginepro::LoadBalancedChannel;
    use shared_proto::pb::tester_client::TesterClient;
    use std::convert::TryInto;

    let load_balanced_channel = LoadBalancedChannel::builder(("my.hostname", 5000))
        .timeout(std::time::Duration::from_secs(10))
        .channel()
        .await
        .expect("failed to construct LoadBalancedChannel");

    let tester_client = TesterClient::new(load_balanced_channel);
}

It’s also possible to eagerly resolve the service endpoints once before LoadBalancedChannel is constructed. .

#[tokio::main]
async fn main() {
    use ginepro::{LoadBalancedChannel, ResolutionStrategy};
    use shared_proto::pb::tester_client::TesterClient;
    use std::time::Duration;
    use std::convert::TryInto;

    let load_balanced_channel = LoadBalancedChannel::builder(("my.hostname", 5000))
        .timeout(std::time::Duration::from_secs(10))
         .resolution_strategy(ginepro::ResolutionStrategy::Eager {
             timeout: Duration::from_secs(20),
         })
        .channel()
        .await
        .expect("failed to construct LoadBalancedChannel");

    let tester_client = TesterClient::new(load_balanced_channel);
}

Internals

The tonic Channel exposes the function balance_channel which returnes a bounded channel through which endpoint changes can be sent. ginepro uses this message passing mechanism to report when servers are added and removed.

Structs

DnsResolver

Implements LookupService by using DNS queries to lookup ServiceDefinition::hostname.

LoadBalancedChannel

Implements tonic GrpcService for a client-side load balanced Channel (using The Power of Two Choices).

LoadBalancedChannelBuilder

Builder to configure and create a LoadBalancedChannel.

ServiceDefinition

Defines a gRPC service with a hostname and a port. The hostname will be resolved to the concrete ips of the service servers.

Enums

ResolutionStrategy

Enumerates the different domain name resolution strategies that the LoadBalancedChannelBuilder supports.

Traits

LookupService

Interface that provides functionality to acquire a list of ips given a valid host name.