Added basic CLI tools.

- Created `ella-cli` crate.
- Implemented `serve` command to run a standalone server.
- Implemented `connect` and `open` commands to start a very basic REPL.
- Added pretty printing for dataframes.

Author: Dexter Duckworth

ella-cli/Cargo.lock

@@ -0,0 +1,29 @@
+[package]
+name = "ella-cli"
+version = "0.1.1"
+edition = "2021"
+authors = ["Dexter Duckworth <[email protected]>"]
+license = "MIT OR Apache-2.0"
+repository = "https://github.com/BlackrockNeurotech/ella"
+description = "CLI tools for working with ella datastores."
+
+[[bin]]
+name = "ella"
+path = "src/main.rs"
+
+[dependencies]
+ella = { path = "../ella", version = "0.1.1" }
+
+anyhow = "1.0.72"
+tracing = "0.1.37"
+tracing-subscriber = "0.3.17"
+futures = "0.3.28"
+tokio = { version = "1.27.0", features = ["full"] }
+mimalloc = { version = "0.1.37", default-features = false }
+clap = { version = "4.3.19", features = ["derive"] }
+dialoguer = { version = "0.10.4", features = ["history"] }
+shlex = "1.1.0"
+
+[package.metadata.docs.rs]
+rustc-args = ["--cfg", "uuid_unstable"]
+rustdoc-args = ["--cfg", "uuid_unstable"]

ella-cli/Cargo.toml

@@ -0,0 +1,13 @@
+# ella-cli
+
+## Installation
+
+### Cargo
+
+```shell
+cargo install --locked ella-cli
+```
+
+## Usage
+
+*[See `ella` CLI reference](docs/reference.md)*

ella-cli/README.md

@@ -0,0 +1,20 @@
+# `ella` Reference
+
+```console
+$ ella -h
+CLI tools for working with ella datastores.
+
+Usage: ella [OPTIONS] <COMMAND>
+
+Commands:
+  serve    Open a datastore as a standalone server
+  connect  Start an interactive session by connecting to an ella API server
+  open     Start an interactive session by opening a local datastore
+  help     Print this message or the help of the given subcommand(s)
+
+Options:
+  -v, --verbose...
+  -q, --quiet...
+  -h, --help        Print help
+  -V, --version     Print version
+```

ella-cli/docs/reference.md

@@ -0,0 +1,12 @@
+/// Start an interactive session by connecting to an ella API server
+#[derive(Debug, clap::Args)]
+pub struct Args {
+    /// Address of the API server
+    #[arg(default_value = "http://localhost:50052")]
+    addr: String,
+}
+
+pub async fn run(args: Args, ctx: crate::Context) -> anyhow::Result<()> {
+    let rt = ella::connect(args.addr).await?;
+    crate::interactive::interactive(rt, 100, ctx).await
+}

ella-cli/src/connect.rs

@@ -0,0 +1,94 @@
+use clap::{CommandFactory, Parser};
+use dialoguer::{console::style, History, Input};
+use ella::Ella;
+use std::collections::VecDeque;
+use tracing::metadata::LevelFilter;
+
+#[derive(Debug, clap::Parser)]
+#[command(
+    multicall = true,
+    help_template = "{all-args}",
+    disable_help_subcommand = true,
+    disable_help_flag = true,
+    disable_version_flag = true
+)]
+pub struct Args {
+    #[command(subcommand)]
+    action: Action,
+}
+
+#[derive(Debug, clap::Subcommand)]
+enum Action {
+    /// Quit the session
+    #[command(visible_alias = "\\q")]
+    Quit,
+    /// Display help
+    #[command(visible_alias = "\\h")]
+    Help,
+    #[command(external_subcommand)]
+    Sql(Vec<String>),
+}
+
+pub async fn interactive(rt: Ella, history: usize, ctx: crate::Context) -> anyhow::Result<()> {
+    crate::init_logging(ctx.verbosity.log_level(LevelFilter::WARN));
+
+    let mut history = CmdHistory::new(history);
+    loop {
+        let cmd = Input::<String>::new()
+            .with_prompt(rt.default_catalog().to_string())
+            .history_with(&mut history)
+            .allow_empty(true)
+            .interact_text()?;
+
+        match shlex::split(&cmd) {
+            Some(args) => match Args::try_parse_from(args) {
+                Ok(args) => match args.action {
+                    Action::Quit => break,
+                    Action::Help => Args::command().print_help().unwrap(),
+                    Action::Sql(sql) => match rt.query(sql.join(" ")).await {
+                        Ok(plan) => match plan.execute().await {
+                            Ok(df) => {
+                                println!("{}", df.pretty_print())
+                            }
+                            Err(error) => {
+                                println!("{}: {}", style("error").red(), error);
+                            }
+                        },
+                        Err(error) => println!("{}: {}", style("error").red(), error),
+                    },
+                },
+                Err(_) => Args::command().print_help().unwrap(),
+            },
+            None => Args::command().print_help().unwrap(),
+        }
+    }
+    Ok(())
+}
+
+#[derive(Debug)]
+struct CmdHistory {
+    capacity: usize,
+    history: VecDeque<String>,
+}
+
+impl CmdHistory {
+    fn new(capacity: usize) -> Self {
+        Self {
+            capacity,
+            history: VecDeque::with_capacity(capacity),
+        }
+    }
+}
+
+impl<T: ToString> History<T> for CmdHistory {
+    fn read(&self, pos: usize) -> Option<String> {
+        self.history.get(pos).cloned()
+    }
+
+    fn write(&mut self, val: &T) {
+        if self.history.len() == self.capacity {
+            self.history.pop_back();
+        }
+        self.history.push_front(val.to_string());
+    }
+}

ella-cli/src/interactive.rs

@@ -0,0 +1,101 @@
+mod connect;
+mod interactive;
+mod open;
+mod serve;
+
+use clap::Parser;
+use tracing::{metadata::LevelFilter, Level};
+use tracing_subscriber::{
+    prelude::__tracing_subscriber_SubscriberExt, util::SubscriberInitExt, EnvFilter, Layer,
+};
+
+#[derive(Debug, Parser)]
+#[command(author, version, about)]
+struct Args {
+    #[command(subcommand)]
+    action: Action,
+    #[command(flatten)]
+    verbosity: Verbosity,
+}
+
+#[derive(Debug, clap::Subcommand)]
+enum Action {
+    Serve(serve::Args),
+    Connect(connect::Args),
+    Open(open::Args),
+}
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let args = Args::parse();
+    let ctx = Context {
+        verbosity: args.verbosity,
+    };
+
+    use Action::*;
+    match args.action {
+        Serve(args) => serve::run(args, ctx).await?,
+        Connect(args) => connect::run(args, ctx).await?,
+        Open(args) => open::run(args, ctx).await?,
+    }
+    Ok(())
+}
+
+#[derive(Debug)]
+pub struct Context {
+    pub verbosity: Verbosity,
+}
+
+#[derive(Debug, Clone, clap::Args)]
+pub struct Verbosity {
+    #[arg(short, long, action = clap::ArgAction::Count, global = true, conflicts_with = "quiet")]
+    verbose: u8,
+    #[arg(short, long, action = clap::ArgAction::Count, global = true, conflicts_with = "verbose")]
+    quiet: u8,
+}
+
+impl Verbosity {
+    pub fn log_level(&self, level: LevelFilter) -> LevelFilter {
+        let mut level: Option<Level> = level.into();
+        for _ in 0..self.verbose {
+            level = match level {
+                None => Some(Level::ERROR),
+                Some(l) => Some(match l {
+                    Level::TRACE => Level::TRACE,
+                    Level::DEBUG => Level::TRACE,
+                    Level::INFO => Level::DEBUG,
+                    Level::WARN => Level::INFO,
+                    Level::ERROR => Level::WARN,
+                }),
+            }
+        }
+
+        for _ in 0..self.quiet {
+            level = match level {
+                None | Some(Level::ERROR) => None,
+                Some(l) => Some(match l {
+                    Level::TRACE => Level::DEBUG,
+                    Level::DEBUG => Level::INFO,
+                    Level::INFO => Level::WARN,
+                    Level::WARN => Level::ERROR,
+                    _ => unreachable!(),
+                }),
+            }
+        }
+        level.into()
+    }
+}
+
+fn init_logging(level: LevelFilter) {
+    tracing_subscriber::registry()
+        .with(
+            tracing_subscriber::fmt::layer().with_filter(
+                EnvFilter::builder()
+                    .with_default_directive(level.into())
+                    .with_env_var("ELLE_LOG")
+                    .from_env()
+                    .unwrap(),
+            ),
+        )
+        .init();
+}

ella-cli/src/main.rs

@@ -0,0 +1,20 @@
+use ella::Path;
+
+/// Start an interactive session by opening a local datastore
+#[derive(Debug, clap::Args)]
+pub struct Args {
+    root: Path,
+    #[arg(long)]
+    create: bool,
+}
+
+pub async fn run(args: Args, ctx: crate::Context) -> anyhow::Result<()> {
+    let rt = if args.create {
+        ella::open(args.root.to_string())
+            .or_create_default()
+            .await?
+    } else {
+        ella::open(args.root.to_string()).await?
+    };
+    crate::interactive::interactive(rt, 100, ctx).await
+}

ella-cli/src/open.rs

@@ -0,0 +1,40 @@
+use tracing::metadata::LevelFilter;
+
+/// Open a datastore as a standalone server.
+///
+/// The datastore will be created if it doesn't already exist.
+#[derive(Debug, clap::Args)]
+pub struct Args {
+    /// Path to the datastore root
+    root: ella::Path,
+    /// Address where the ella API will be served
+    #[arg(short, long, default_value = "localhost:50052")]
+    addr: String,
+    /// Do not create the datastore if it doesn't already exist
+    #[arg(long)]
+    no_create: bool,
+}
+
+pub async fn run(args: Args, ctx: crate::Context) -> anyhow::Result<()> {
+    crate::init_logging(ctx.verbosity.log_level(LevelFilter::INFO));
+
+    tracing::info!("starting elle server");
+    let rt = if args.no_create {
+        ella::open(args.root.to_string())
+            .and_serve(args.addr)?
+            .await
+    } else {
+        ella::open(args.root.to_string())
+            .or_create_default()
+            .and_serve(args.addr)?
+            .await
+    }?;
+    if let Err(error) = tokio::signal::ctrl_c().await {
+        tracing::error!(?error, "failed to register signal listener");
+    }
+
+    tracing::info!("shutting down server");
+    rt.shutdown().await?;
+
+    Ok(())
+}

ella-cli/src/serve.rs

@@ -14,7 +14,7 @@ pub trait TensorValue: Debug + Clone + PartialEq + PartialOrd + Send + Sync + 's
     /// Masked value type. For `Option<T>` this is `Option<T>`.
     /// For all other `T` this should be `Option<T>`.
     type Masked: TensorValue<Array = Self::Array>;
-    /// Unmasked value type. For Option<T> shis is `T`. For all other `T` this should be `T`.
+    /// Unmasked value type. For `Option<T>` this is `T`. For all other `T` this should be `T`.
     type Unmasked: TensorValue<Array = Self::Array>;
 
     const TENSOR_TYPE: TensorType;
@@ -84,7 +84,7 @@ pub trait TensorValue: Debug + Clone + PartialEq + PartialOrd + Send + Sync + 's
     ///
     /// Panics if `offset + length` > `array.len()`.
     fn slice(array: &Self::Array, offset: usize, length: usize) -> Self::Array;
-    /// Constructs an array from [`ArrowData`].
+    /// Constructs an array from [`ArrayData`].
     ///
     /// Panics if `data` is not convertable to [`Self::Array`].
     fn from_array_data(data: ArrayData) -> Self::Array;