Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: add env vars for proxy configurations #1120

Open
wants to merge 17 commits into
base: next
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

16 changes: 16 additions & 0 deletions bin/proving-service/.env
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
PROXY_HOST="0.0.0.0"
PROXY_PORT="8082"
PROXY_WORKERS_UPDATE_PORT="8083"
PROXY_TIMEOUT_SECS="100"
PROXY_CONNECTION_TIMEOUT_SECS="10"
PROXY_MAX_QUEUE_ITEMS="10"
PROXY_MAX_RETRIES_PER_REQUEST="1"
PROXY_MAX_REQ_PER_SEC="5"
PROXY_AVAILABLE_WORKERS_POLLING_TIME_MS="20"
PROXY_HEALTH_CHECK_INTERVAL_SECS="1"
PROXY_PROMETHEUS_HOST="127.0.0.1"
PROXY_PROMETHEUS_PORT="6192"
RUST_LOG="info"
WORKER_HOST="0.0.0.0"
WORKER_PORT="8084"
WORKERS="0.0.0.0:8084,0.0.0.0:50051"
bobbinth marked this conversation as resolved.
Show resolved Hide resolved
3 changes: 2 additions & 1 deletion bin/proving-service/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,8 @@ async-trait = "0.1"
axum = { version = "0.7" }
bytes = "1.0"
clap = { version = "4.5", features = ["derive", "env"] }
figment = { version = "0.10", features = ["toml", "env"] }
dotenvy = "0.15"
figment = { version = "0.10", features = ["env"] }
bobbinth marked this conversation as resolved.
Show resolved Hide resolved
miden-lib = { workspace = true, default-features = false }
miden-objects = { workspace = true, default-features = false, features = ["std"] }
miden-tx = { workspace = true, default-features = false, features = ["std"] }
Expand Down
52 changes: 28 additions & 24 deletions bin/proving-service/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,54 +24,58 @@ To start the worker service you will need to run:
miden-proving-service start-worker --host 0.0.0.0 --port 8082
```

This will spawn a worker using the hosts and ports defined in the command options. In case that one of the values is not present, it will default to `0.0.0.0` for the host and `50051` for the port.
This will spawn a worker using the hosts and ports defined in the command options. In case that one of the values is not present, it will default to `0.0.0.0` for the host and `50051` for the port. The host and port can also be set using the `WORKER_HOST` and `WORKER_PORT` environment variables.

## Proxy

First, you need to create a configuration file for the proxy with:
To use the proxy service, you will need an `.env` file with the following configuration, if any of the values are not present, it will be completed with the default ones:

```bash
miden-proving-service init
```

This will create the `miden-proving-service.toml` file in your current directory. This file will hold the configuration for the proxy. You can modify the configuration by changing the host and ports of the services, the maximum size of the queue, among other options. An example configuration is:

```toml
```env
# Host of the proxy server
host = "0.0.0.0"
PROXY_HOST="0.0.0.0"
# Port of the proxy server
port = 8082
PROXY_PORT="8082"
# Host of the workers update endpoint
PROXY_WORKERS_UPDATE_PORT="8083"
# Timeout for a new request to be completed
timeout_secs = 100
PROXY_TIMEOUT_SECS="100"
# Timeout for establishing a connection to the worker
connection_timeout_secs = 10
PROXY_CONNECTION_TIMEOUT_SECS="10"
# Maximum amount of items that a queue can handle
max_queue_items = 10
PROXY_MAX_QUEUE_ITEMS="10"
# Maximum amount of retries that a request can take
max_retries_per_request = 1
PROXY_MAX_RETRIES_PER_REQUEST="1"
# Maximum amount of requests that a given IP address can make per second
max_req_per_sec = 5
PROXY_MAX_REQ_PER_SEC="5"
# Time to wait before checking the availability of workers
available_workers_polling_time_ms = 20
PROXY_AVAILABLE_WORKERS_POLLING_TIME_MS="20"
# Interval to check the health of the workers
health_check_interval_secs = 1
PROXY_HEALTH_CHECK_INTERVAL_SECS="1"
# Host of the metrics server
prometheus_host = "127.0.0.1"
PROXY_PROMETHEUS_HOST="127.0.0.1"
# Port of the metrics server
prometheus_port = 6192
PROXY_PROMETHEUS_PORT="6192"
# Log level
RUST_LOG="info"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we only use clap then I would suggest either directly copying --help output here, or only documenting the important ones and tell the user to check out more options with --help.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't have this as command options, but are used to create the ProxyConfig struct. ATM, I;ve removed the TOML file and we are trying to create the ProxyConfig struct with the env vars or default values if not present. But since we don't have it as options, --help is not printing them.

Though I can change it to be part of the command if we consider that is it more useful that way.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

imo the default should always be cli unless there is a compelling reason not to. I would make these all clap variables with these default values, and with the env args set.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this would basically mean that we merge StartProxy command and ProxyConfig structs, right?

Copy link
Contributor

@Mirko-von-Leipzig Mirko-von-Leipzig Feb 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correct yes, at least from the external API sense.

One might still keep the ProxyConfig struct to decouple the cli interface from the proxy code but whether or not that's applicable depends.

A good illustration of this ^^ is the node where currently each component has its own config, as well as a "normalized" variant for miden-node start node. When we refactor that we'll keep component config structs (but without toml support). Then its up to the clap/main binary code to convert between the cli args and the component config as it sees fit. e.g.

let cli_args = clap::parse()?;

let proxy_handle = Proxy {
    endpoint: cli_args.endpoint,
    timeout: cli_args.timeout,
    request: RequestLimits {
        retries: cli_args.requests.max_retries,
        ...
    },
    ...
}.spawn();

```

The proving service can also use environment variables to set the configuration. The environment variables should have the same name as the configuration file but in uppercase and with the prefix `PROXY_`. For example, the `host` value in the configuration file can be set using the `PROXY_HOST` environment variable.
An example `.env` file is provided in the crate's root directory.
bobbinth marked this conversation as resolved.
Show resolved Hide resolved

Then, to start the proxy service, you will need to run:

```bash
miden-proving-service start-proxy [worker1] [worker2] ... [workerN]
miden-proving-service start-proxy [worker1],[worker2],...,[workerN]
```

This command will start the proxy using the workers passed as arguments. The workers should be in the format `host:port`. If no workers are passed, the proxy will start without any workers and will not be able to handle any requests until one is added through the `miden-proving-service add-worker` command.

At the moment, when a worker added to the proxy stops working and can not connect to it for a request, the connection is marked as retriable meaning that the proxy will try reaching another worker. The number of retries is configurable via the `max_retries_per_request` value in the configuration file.
The proxy service can also be started using the `PROXY_WORKERS` environment variable, which should contain a comma-separated list of workers.

```bash
WORKERS="0.0.0.0:8084,0.0.0.0:8085" miden-proving-service start-proxy
```

At the moment, when a worker added to the proxy stops working and can not connect to it for a request, the connection is marked as retriable meaning that the proxy will try reaching another worker. The number of retries is configurable via the `PROXY_MAX_RETRIES_PER_REQUEST` environmental variable.

## Updating workers on a running proxy

Expand Down Expand Up @@ -122,7 +126,7 @@ If Docker is not an option, Jaeger can also be set up directly on your machine o

## Metrics

The proxy includes a service that exposes metrics to be consumed by [Prometheus](https://prometheus.io/docs/introduction/overview/). This service is always enabled and uses the host and port defined in the `miden-proving-service.toml` file.
The proxy includes a service that exposes metrics to be consumed by [Prometheus](https://prometheus.io/docs/introduction/overview/). This service is always enabled and uses the host and port defined in the `.env` file through the `PROXY_PROMETHEUS_HOST` and `PROXY_PROMETHEUS_PORT` variables.

The metrics architecture works by having the proxy expose metrics at an endpoint (`/metrics`) in a format Prometheus can read. Prometheus periodically scrapes this endpoint, adds timestamps to the metrics, and stores them in its time-series database. Then, we can use tools like Grafana to query Prometheus and visualize these metrics in configurable dashboards.

Expand Down
48 changes: 0 additions & 48 deletions bin/proving-service/src/commands/init.rs

This file was deleted.

28 changes: 5 additions & 23 deletions bin/proving-service/src/commands/mod.rs
Original file line number Diff line number Diff line change
@@ -1,18 +1,16 @@
use clap::Parser;
use figment::{
providers::{Env, Format, Serialized, Toml},
providers::{Env, Serialized},
Figment,
};
use init::Init;
use proxy::StartProxy;
use serde::{Deserialize, Serialize};
use tracing::instrument;
use update_workers::{AddWorkers, RemoveWorkers, UpdateWorkers};
use worker::StartWorker;

use crate::utils::{MIDEN_PROVING_SERVICE, PROVING_SERVICE_CONFIG_FILE_NAME};
use crate::utils::MIDEN_PROVING_SERVICE;

pub mod init;
pub mod proxy;
pub mod update_workers;
pub mod worker;
Expand Down Expand Up @@ -78,15 +76,9 @@ impl ProxyConfig {
/// [PROVING_SERVICE_CONFIG_FILE_NAME] constant in the current directory. It will then merge
/// the TOML file with the environment variables with the `PROXY_` prefix.
pub(crate) fn load() -> Result<ProxyConfig, String> {
let config_path = std::env::current_dir()
.map_err(|e| e.to_string())?
.join(PROVING_SERVICE_CONFIG_FILE_NAME);

Figment::new()
// Start with default values
.merge(Serialized::defaults(ProxyConfig::default()))
// Add TOML config file
.merge(Toml::file(config_path))
// Add environment variables with PROXY_ prefix
.merge(Env::prefixed(ENV_PREFIX).split("_"))
.extract()
Expand All @@ -110,23 +102,17 @@ pub struct Cli {
/// CLI actions
#[derive(Debug, Parser)]
pub enum Command {
/// Creates a config file for the proxy.
///
/// This method will create a new config file in the current working directory with default
/// values. The file will be named as defined in the
/// [PROVING_SERVICE_CONFIG_FILE_NAME] constant.
Init(Init),
/// Starts the workers with the configuration defined in the command.
StartWorker(StartWorker),
/// Starts the proxy defined in the config file.
/// Starts the proxy.
StartProxy(StartProxy),
/// Adds workers to the proxy.
///
/// This method will make a request to the proxy defined in the config file to add workers.
/// This method will make a request to the proxy adding workers.
AddWorkers(AddWorkers),
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: should the text here be: "This command will make a request to the proxy to add the specified workers."

/// Removes workers from the proxy.
///
/// This method will make a request to the proxy defined in the config file to remove workers.
/// This method will make a request to the proxy removing workers.
RemoveWorkers(RemoveWorkers),
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: should the text here be: "This command will make a request to the proxy to remove the specified workers."

}

Expand All @@ -138,10 +124,6 @@ impl Cli {
// For the `StartWorker` command, we need to create a new runtime and run the worker
Command::StartWorker(worker_init) => worker_init.execute().await,
Command::StartProxy(proxy_init) => proxy_init.execute().await,
Command::Init(init) => {
// Init does not require async, so run directly
init.execute()
},
Command::AddWorkers(update_workers) => {
let update_workers: UpdateWorkers = update_workers.clone().into();
update_workers.execute().await
Expand Down
2 changes: 1 addition & 1 deletion bin/proving-service/src/commands/proxy.rs
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ pub struct StartProxy {
/// List of workers as host:port strings.
///
/// Example: `127.0.0.1:8080 192.168.1.1:9090`
#[clap(value_name = "WORKERS", env = "WORKERS")]
#[clap(value_name = "WORKERS", env = "WORKERS", value_delimiter = ',')]
workers: Vec<String>,
bobbinth marked this conversation as resolved.
Show resolved Hide resolved
}

Expand Down
2 changes: 2 additions & 0 deletions bin/proving-service/src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ use utils::setup_tracing;
async fn main() -> Result<(), String> {
use clap::Parser;

dotenvy::dotenv().map_err(|e| format!("Failed to load .env file: {}", e))?;

setup_tracing()?;

// read command-line args
Expand Down
3 changes: 0 additions & 3 deletions bin/proving-service/src/utils.rs
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,6 @@ pub const MIDEN_PROVING_SERVICE: &str = "miden-proving-service";

const RESOURCE_EXHAUSTED_CODE: u16 = 8;

/// Name of the configuration file
pub const PROVING_SERVICE_CONFIG_FILE_NAME: &str = "miden-proving-service.toml";

/// Initializes and configures the global tracing and telemetry system for the CLI, worker and
/// proxy services.
///
Expand Down
Loading