Add "list instances" endpoint to improve discoverability, reformat start.sh, misc. improvements

Author: DJAndries

Cargo.lock

@@ -11,7 +11,7 @@ use tracing::{debug, instrument};
 use crate::state::{OPRFInstance, OPRFState};
 use ppoprf::ppoprf;
 
-/// Request format for the randomness endpoint
+/// Request structure for the randomness endpoint
 #[derive(Deserialize, Debug)]
 pub struct RandomnessRequest {
     /// Array of points to evaluate
@@ -21,7 +21,7 @@ pub struct RandomnessRequest {
     epoch: Option<u8>,
 }
 
-/// Response format for the randomness endpoint
+/// Response structure for the randomness endpoint
 #[derive(Serialize, Debug)]
 pub struct RandomnessResponse {
     /// Resulting points from the OPRF valuation
@@ -32,26 +32,34 @@ pub struct RandomnessResponse {
     epoch: u8,
 }
 
-/// Response format for the info endpoint
+/// Response structure for the info endpoint
 /// Rename fields to match the earlier golang implementation.
 #[derive(Serialize, Debug)]
+#[serde(rename_all = "camelCase")]
 pub struct InfoResponse {
     /// ServerPublicKey used to verify zero-knowledge proof
-    #[serde(rename = "publicKey")]
     public_key: String,
     /// Currently active randomness epoch
-    #[serde(rename = "currentEpoch")]
     current_epoch: u8,
     /// Timestamp of the next epoch rotation
     /// This should be a string in RFC 3339 format,
     /// e.g. 2023-03-14T16:33:05Z.
-    #[serde(rename = "nextEpochTime")]
     next_epoch_time: Option<String>,
     /// Maximum number of points accepted in a single request
-    #[serde(rename = "maxPoints")]
     max_points: usize,
 }
 
+/// Response structure for the "list instances" endpoint.
+#[derive(Serialize, Debug)]
+#[serde(rename_all = "camelCase")]
+pub struct ListInstancesResponse {
+    /// A list of available instances on the server.
+    instances: Vec<String>,
+    /// The default instance on this server.
+    /// A requests made to /info and /randomness will utilize this instance.
+    default_instance: String,
+}
+
 /// Response returned to report error conditions
 #[derive(Serialize, Debug)]
 struct ErrorResponse {
@@ -112,14 +120,14 @@ impl axum::response::IntoResponse for Error {
 
 type Result<T> = std::result::Result<T, Error>;
 
-fn get_server_from_state(
-    state: &OPRFState,
-    instance_name: String,
-) -> Result<RwLockReadGuard<'_, OPRFInstance>> {
+fn get_server_from_state<'a>(
+    state: &'a OPRFState,
+    instance_name: &'a str,
+) -> Result<RwLockReadGuard<'a, OPRFInstance>> {
     Ok(state
         .instances
-        .get(&instance_name)
-        .ok_or(Error::InstanceNotFound(instance_name))?
+        .get(instance_name)
+        .ok_or_else(|| Error::InstanceNotFound(instance_name.to_string()))?
         .read()?)
 }
 
@@ -131,7 +139,7 @@ async fn randomness(
     request: RandomnessRequest,
 ) -> Result<Json<RandomnessResponse>> {
     debug!("recv: {request:?}");
-    let state = get_server_from_state(&state, instance_name)?;
+    let state = get_server_from_state(&state, &instance_name)?;
     let epoch = request.epoch.unwrap_or(state.epoch);
     if epoch != state.epoch {
         return Err(Error::BadEpoch(epoch));
@@ -180,7 +188,7 @@ pub async fn specific_instance_randomness(
 #[instrument(skip(state))]
 async fn info(state: OPRFState, instance_name: String) -> Result<Json<InfoResponse>> {
     debug!("recv: info request");
-    let state = get_server_from_state(&state, instance_name)?;
+    let state = get_server_from_state(&state, &instance_name)?;
     let public_key = state.server.get_public_key().serialize_to_bincode()?;
     let public_key = BASE64.encode(public_key);
     let response = InfoResponse {
@@ -206,3 +214,11 @@ pub async fn specific_instance_info(
 ) -> Result<Json<InfoResponse>> {
     info(state, instance_name).await
 }
+
+// Lists all available instances, as well as the default instance
+pub async fn list_instances(State(state): State<OPRFState>) -> Result<Json<ListInstancesResponse>> {
+    Ok(Json(ListInstancesResponse {
+        instances: state.instances.keys().cloned().collect(),
+        default_instance: state.default_instance.clone(),
+    }))
+}

src/handler.rs

@@ -78,6 +78,7 @@ fn app(oprf_state: OPRFState) -> Router {
             "/instances/:instance/info",
             get(handler::specific_instance_info),
         )
+        .route("/instances", get(handler::list_instances))
         // Endpoints for default instance
         .route("/randomness", post(handler::default_instance_randomness))
         .route("/info", get(handler::default_instance_info))

src/main.rs

@@ -1,26 +1,26 @@
 #!/bin/sh
 
 nitriding \
-	-fqdn "star-randsrv.bsg.brave.com" \
-	-appurl "https://github.com/brave/star-randsrv" \
-	-appwebsrv "http://127.0.0.1:8080" \
-	-prometheus-port 9090 \
-	-vsock-ext \
-	-disable-keep-alives \
-	-prometheus-namespace "nitriding" \
-	-extport 443 \
-	-intport 8081 &
+  -fqdn "star-randsrv.bsg.brave.com" \
+  -appurl "https://github.com/brave/star-randsrv" \
+  -appwebsrv "http://127.0.0.1:8080" \
+  -prometheus-port 9090 \
+  -vsock-ext \
+  -disable-keep-alives \
+  -prometheus-namespace "nitriding" \
+  -extport 443 \
+  -intport 8081 &
 echo "[sh] Started nitriding as reverse proxy."
 
 sleep 1
 
 star-randsrv \
-	--instance-name weekly \
-	--epoch-duration "1w" \
-	--instance-name daily \
-	--epoch-duration "1d" \
-	--instance-name monthly \
-	--epoch-duration "1mon" \
-	--epoch-base-time 2023-05-01T00:00:00Z \
-	--increase-nofile-limit
+  --instance-name typical \
+  --epoch-duration "1w" \
+  --instance-name express \
+  --epoch-duration "1d" \
+  --instance-name slow \
+  --epoch-duration "1mon" \
+  --epoch-base-time 2023-05-01T00:00:00Z \
+  --increase-nofile-limit
 echo "[sh] Started star-randsrv."