Merge pull request #70 from NREL/rjf/gbfs-cli

scaffold a CLI for bambam GBFS downloads

Author: robfitzgerald

rust/Cargo.toml

@@ -34,6 +34,7 @@ geozero = { version = "0.14.0", features = ["with-wkb"] }
 gtfs-structures = "0.43.0"
 h3o = { version = "0.8.0", features = ["serde", "geo"] }
 hex = "0.4.3"
+humantime = "2.3.0"
 inventory = { version = "0.3.21" }
 itertools = { version = "0.14.0" }
 jsonpath-rust = { version = "1.0.4" }
@@ -52,6 +53,7 @@ rstar = { version = "0.12.0" }
 serde = { version = "1.0.160", features = ["derive"] }
 serde_json = { version = "1.0" }
 serde_arrow = { version = "0.13.7", features = ["arrow-55"] }
+serde_with = { version = "3.0", features = ["chrono_0_4"] }
 shapefile = { version = "0.7.0", features = ["geo-types"] }
 skiplist = "0.5.1"
 thiserror = "2.0.12"

rust/bambam-gbfs/Cargo.toml

@@ -6,8 +6,15 @@ license = "BSD-3-Clause"
 description = "GBFS Extensions for The Behavior and Advanced Mobility Big Access Model"
 
 [dependencies]
+env_logger = { workspace = true }
 routee-compass-core = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
+serde_with = { workspace = true }
+chrono = { workspace = true }
+humantime = { workspace = true }
+log = { workspace = true }
 geo = { workspace = true }
-reqwest = { workspace = true }
+reqwest = { workspace = true }
+clap = { workspace = true }
+kdam = { workspace = true }

rust/bambam-gbfs/README.md

@@ -0,0 +1,60 @@
+# bambam-gbfs
+
+tooling for building and running BAMBAM models from GBFS sources.
+
+## CLI Usage
+
+example CLI calls:
+
+### top-level GBFS CLI
+
+```
+% ./target/release/bambam-gbfs
+GBFS Extensions for The Behavior and Advanced Mobility Big Access Model
+
+Usage: bambam-gbfs <COMMAND>
+
+Commands:
+  download  runs a GBFS download, writing data from some source URL to an output directory
+  help      Print this message or the help of the given subcommand(s)
+
+Options:
+  -h, --help     Print help
+  -V, --version  Print version
+```
+
+### GBFS download command
+
+```
+% cd rust
+% cargo build -r 
+% ./target/release/bambam-gbfs download --help
+runs a GBFS download, writing data from some source URL to an output directory
+
+Usage: bambam-gbfs download [OPTIONS] --gbfs-url <GBFS_URL>
+
+Options:
+  -g, --gbfs-url <GBFS_URL>
+          a GBFS API URL
+  -o, --output-directory <OUTPUT_DIRECTORY>
+          output directory path [default: .]
+  -c, --collect-duration <COLLECT_DURATION>
+          duration to collect data rows. provide in human-readable time values 2m, 30s, 2h, 2days... [default: 10m]
+  -h, --help
+          Print help
+  -V, --version
+          Print version
+```
+
+### running GBFS download with arguments
+
+this isn't yet implemented so with debug logging enabled, the command will run the download function, log the arguments, then panic when it hits the todo!() line.
+
+```
+% RUST_LOG=debug ./target/release/bambam-gbfs download -g https://example.com
+[2025-12-22T17:15:15Z DEBUG bambam_gbfs::app::download::run] run_gbfs_download with url=https://example.com, out_dir=".", duration (seconds)=600
+
+thread 'main' (2745448) panicked at bambam-gbfs/src/app/download/run.rs:20:5:
+not yet implemented: download + post-processing logic
+note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
+```

rust/bambam-gbfs/src/app/download/mod.rs

@@ -0,0 +1,3 @@
+mod run;
+
+pub use run::run_gbfs_download;

rust/bambam-gbfs/src/app/download/run.rs

@@ -0,0 +1,21 @@
+use std::path::Path;
+
+use chrono::TimeDelta;
+
+/// downloads GBFS data for some duration. aggregates the resulting rows and writes them
+/// to files to be consumed by BAMBAM.
+///
+/// # Arguments
+/// * url - URL to the GBFS dataset
+/// * out_dir - output directory to write the processed GBFS data
+/// * dur - how long to poll the GBFS API
+///
+/// # Result
+/// If successful, returns nothing, otherwise an error
+pub fn run_gbfs_download(url: &str, out_dir: &Path, dur: &TimeDelta) -> Result<(), String> {
+    let dur_secs = dur.as_seconds_f64();
+    log::debug!(
+        "run_gbfs_download with url={url}, out_dir={out_dir:?}, duration (seconds)={dur_secs}"
+    );
+    todo!("download + post-processing logic")
+}

rust/bambam-gbfs/src/app/gbfs_cli.rs

@@ -0,0 +1,55 @@
+use std::path::Path;
+
+use chrono::TimeDelta;
+use clap::{Parser, Subcommand};
+use serde::{Deserialize, Serialize};
+
+/// command line tool providing GBFS processing scripts
+#[derive(Parser)]
+#[command(author, version, about, long_about = None)]
+#[command(propagate_version = true)]
+pub struct GbfsCliArguments {
+    /// select the GBFS operation to run
+    #[command(subcommand)]
+    pub op: GbfsOperation,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, Subcommand)]
+pub enum GbfsOperation {
+    /// runs a GBFS download, writing data from some source URL
+    /// to an output directory.
+    Download {
+        /// a GBFS API URL
+        #[arg(short, long)]
+        gbfs_url: String,
+        /// output directory path.
+        #[arg(short, long, default_value_t = String::from("."))]
+        output_directory: String,
+        /// duration to collect data rows. provide in human-readable time values
+        /// 2m, 30s, 2h, 2days...
+        #[arg(short, long, value_parser = parse_duration, default_value = "10m")]
+        collect_duration: TimeDelta,
+    },
+}
+
+impl GbfsOperation {
+    pub fn run(&self) -> Result<(), String> {
+        match self {
+            GbfsOperation::Download {
+                gbfs_url,
+                output_directory,
+                collect_duration,
+            } => crate::app::download::run_gbfs_download(
+                gbfs_url,
+                Path::new(output_directory),
+                collect_duration,
+            ),
+        }
+    }
+}
+
+fn parse_duration(s: &str) -> Result<chrono::TimeDelta, String> {
+    let std_duration =
+        humantime::parse_duration(s).map_err(|e| format!("Invalid duration: {}", e))?;
+    chrono::TimeDelta::from_std(std_duration).map_err(|e| format!("TimeDelta out of range: {}", e))
+}

rust/bambam-gbfs/src/app/mod.rs

@@ -0,0 +1,4 @@
+mod gbfs_cli;
+
+pub mod download;
+pub use gbfs_cli::GbfsCliArguments;

rust/bambam-gbfs/src/lib.rs

@@ -1 +1,2 @@
+pub mod app;
 pub mod model;

rust/bambam-gbfs/src/main.rs

@@ -0,0 +1,14 @@
+use bambam_gbfs::app::GbfsCliArguments;
+use clap::Parser;
+
+fn main() {
+    env_logger::init();
+    let args = GbfsCliArguments::parse();
+    match args.op.run() {
+        Ok(_) => log::info!("finished."),
+        Err(e) => {
+            log::error!("failed running bambam_gbfs: {e}");
+            std::process::exit(1);
+        }
+    }
+}