feat: CLI to manage last caches (#25168)

* feat: new last-cache CLI

This adds two new CLIs:

influxdb3 last-cache create
influxdb3 last-cache delete

These utilize the new underlying APIs/client methods for the last-n-value
cache feature.

* refactor: switch around the token CLI to new convention

* docs: re-word CLI docs

influxdb3/src/commands/last_cache/create.rs

@@ -0,0 +1,73 @@
+use std::error::Error;
+
+use secrecy::ExposeSecret;
+
+use crate::commands::common::InfluxDb3Config;
+
+#[derive(Debug, clap::Parser)]
+pub struct Config {
+    #[clap(flatten)]
+    influxdb3_config: InfluxDb3Config,
+
+    /// The table name for which the cache is being created
+    #[clap(short = 't', long = "table")]
+    table: String,
+
+    /// Give a name for the cache.
+    #[clap(long = "cache-name")]
+    cache_name: Option<String>,
+
+    /// Which columns in the table to use as keys in the cache
+    #[clap(long = "key-columns")]
+    key_columns: Option<Vec<String>>,
+
+    /// Which columns in the table to store as values in the cache
+    #[clap(long = "value-columns")]
+    value_columns: Option<Vec<String>>,
+
+    /// The number of entries per unique key column combination the cache will store
+    #[clap(long = "count")]
+    count: Option<usize>,
+
+    /// The time-to-live (TTL) for entries in a cache in seconds
+    #[clap(long = "ttl")]
+    ttl: Option<u64>,
+}
+
+pub(super) async fn command(config: Config) -> Result<(), Box<dyn Error>> {
+    let InfluxDb3Config {
+        host_url,
+        database_name,
+        auth_token,
+    } = config.influxdb3_config;
+    let mut client = influxdb3_client::Client::new(host_url)?;
+    if let Some(t) = auth_token {
+        client = client.with_auth_token(t.expose_secret());
+    }
+    let mut b = client.api_v3_configure_last_cache_create(database_name, config.table);
+
+    // Add optional parameters:
+    if let Some(name) = config.cache_name {
+        b = b.name(name);
+    }
+    if let Some(keys) = config.key_columns {
+        b = b.key_columns(keys);
+    }
+    if let Some(vals) = config.value_columns {
+        b = b.value_columns(vals);
+    }
+    if let Some(count) = config.count {
+        b = b.count(count);
+    }
+    if let Some(ttl) = config.ttl {
+        b = b.ttl(ttl);
+    }
+
+    // Make the request:
+    match b.send().await? {
+        Some(cache_name) => println!("new cache created: {cache_name}"),
+        None => println!("a cache already exists for the provided parameters"),
+    }
+
+    Ok(())
+}

influxdb3/src/commands/last_cache/delete.rs

@@ -0,0 +1,38 @@
+use std::error::Error;
+
+use secrecy::ExposeSecret;
+
+use crate::commands::common::InfluxDb3Config;
+
+#[derive(Debug, clap::Parser)]
+pub struct Config {
+    #[clap(flatten)]
+    influxdb3_config: InfluxDb3Config,
+
+    /// The table under which the cache is being deleted
+    #[clap(short = 't', long = "table")]
+    table: String,
+
+    /// The name of the cache being deleted
+    #[clap(short = 'n', long = "cache-name")]
+    cache_name: String,
+}
+
+pub(super) async fn command(config: Config) -> Result<(), Box<dyn Error>> {
+    let InfluxDb3Config {
+        host_url,
+        database_name,
+        auth_token,
+    } = config.influxdb3_config;
+    let mut client = influxdb3_client::Client::new(host_url)?;
+    if let Some(t) = auth_token {
+        client = client.with_auth_token(t.expose_secret());
+    }
+    client
+        .api_v3_configure_last_cache_delete(database_name, config.table, config.cache_name)
+        .await?;
+
+    println!("last cache deleted successfully");
+
+    Ok(())
+}

influxdb3/src/commands/last_cache/mod.rs

@@ -0,0 +1,25 @@
+use std::error::Error;
+
+pub mod create;
+pub mod delete;
+
+#[derive(Debug, clap::Parser)]
+pub(crate) struct Config {
+    #[clap(subcommand)]
+    command: Command,
+}
+
+#[derive(Debug, clap::Parser)]
+enum Command {
+    /// Create a new last-n-value cache
+    Create(create::Config),
+    /// Delete an existing last-n-value cache
+    Delete(delete::Config),
+}
+
+pub(crate) async fn command(config: Config) -> Result<(), Box<dyn Error>> {
+    match config.command {
+        Command::Create(config) => create::command(config).await,
+        Command::Delete(config) => delete::command(config).await,
+    }
+}

influxdb3/src/commands/token.rs

@@ -15,12 +15,13 @@ pub struct Config {
 
 #[derive(Debug, clap::Parser)]
 pub enum SubCommand {
-    Token,
+    /// Create a new auth token
+    Create,
 }
 
 pub fn command(config: Config) -> Result<(), Box<dyn Error>> {
     match config.cmd {
-        SubCommand::Token => {
+        SubCommand::Create => {
             let token = {
                 let mut token = String::from("apiv3_");
                 let mut key = [0u8; 64];

influxdb3/src/main.rs

@@ -26,9 +26,10 @@ use trogging::{
 
 mod commands {
     pub(crate) mod common;
-    pub mod create;
+    pub mod last_cache;
     pub mod query;
     pub mod serve;
+    pub mod token;
     pub mod write;
 }
 
@@ -85,8 +86,11 @@ enum Command {
     /// Perform a set of writes to a running InfluxDB 3.0 server
     Write(commands::write::Config),
 
-    /// Create new resources
-    Create(commands::create::Config),
+    /// Manage tokens for your InfluxDB 3.0 server
+    Token(commands::token::Config),
+
+    /// Manage last-n-value caches
+    LastCache(commands::last_cache::Config),
 }
 
 fn main() -> Result<(), std::io::Error> {
@@ -132,9 +136,15 @@ fn main() -> Result<(), std::io::Error> {
                     std::process::exit(ReturnCode::Failure as _)
                 }
             }
-            Some(Command::Create(config)) => {
-                if let Err(e) = commands::create::command(config) {
-                    eprintln!("Create command failed: {e}");
+            Some(Command::Token(config)) => {
+                if let Err(e) = commands::token::command(config) {
+                    eprintln!("Token command failed: {e}");
+                    std::process::exit(ReturnCode::Failure as _)
+                }
+            }
+            Some(Command::LastCache(config)) => {
+                if let Err(e) = commands::last_cache::command(config).await {
+                    eprintln!("Last Cache command failed: {e}");
                     std::process::exit(ReturnCode::Failure as _)
                 }
             }