Client subcommand for interacting with service (#104)

Provides a more convenient way of generating and passing auth tokens and
saves writing graphql queries in the terminal to test things using curl.

New features are behind the `client` subcommand which itself has three
further commands:
* configuration: Show/query existing configurations
* configure: Update/add new configurations
* visit-directory: Generate the visit directory for the given instrument

As part of the changes, the '--db' option has been made specific to the
serve command as it is not required elsewhere.

Author: tpoliaw

Cargo.lock

@@ -10,6 +10,10 @@ rust-version = "1.83"
 [lints.clippy]
 unwrap_used = "deny"
 
+[features]
+default = ["client"]
+client = ["dep:dirs", "dep:graphql_client", "dep:openidconnect", "dep:toml"]
+
 [dependencies]
 async-graphql = { version = "7.0.16", features = ["tracing"] }
 async-graphql-axum = "7.0.16"
@@ -32,6 +36,12 @@ tracing-opentelemetry = "0.30.0"
 tracing-subscriber = { version = "0.3.19", features = ["env-filter"] }
 url = "2.5.4"
 
+# Dependencies required if building with client subcommand
+dirs = { version = "6.0.0", optional = true }
+graphql_client = { version = "0.14.0", optional = true }
+openidconnect = { version = "4.0.0", optional = true }
+toml = { version = "0.8.20", optional = true }
+
 [dev-dependencies]
 assert_matches = "1.5.0"
 async-std = { version = "1.13.1", features = ["attributes"], default-features = false }

Cargo.toml

@@ -14,6 +14,7 @@ COPY ./.env ./.env
 COPY ./src ./src
 COPY ./.sqlx ./.sqlx
 COPY ./migrations ./migrations
+COPY ./queries ./queries
 COPY ./static ./static
 # Copy the git directory purely so that the commit information can be included
 # build details provided by the 'built' library. See #99

Dockerfile

@@ -298,5 +298,109 @@ mutation {
 }
 ```
 
+## Using CLI client
+
+If the application is built with the `client` feature enabled, there is a
+`client` subcommand available from the CLI to query and configure the service.
+The help covers the basic use.
+
+<details><summary>Output from `numtracker client --help`</summary>
+
+```
+View and update beamline configurations provided by an instance of the service
+
+Usage: numtracker client [OPTIONS] <COMMAND>
+
+Commands:
+  configuration    Query existing configurations
+  configure        Update or add new configurations
+  visit-directory  Query for templated data
+  help             Print this message or the help of the given subcommand(s)
+
+Options:
+  -H, --host <HOST>  [env: NUMTRACKER_SERVICE_HOST=]
+      --auth <AUTH>  [env: NUMTRACKER_AUTH_HOST=]
+  -h, --help         Print help
+
+Logging/Debug:
+  -v, --verbose...  Increase the level of logs written to stderr
+  -q, --quiet       Disable all output to stderr/stdout
+```
+</details>
+
+### Configure
+
+The `configure` subcommand corresponds to the `configure` mutation from graphql.
+If a beamline is already present, this can be used to update individual fields.
+If the beamline is not present, all template fields must be present.
+
+```bash
+$ numtracker client configure i22 \
+    --visit '/tmp/{instrument}/data/{year}/{visit}'\
+    --scan '{subdirectory}/{instrument}-{scan_number}'\
+    --detector '{subdirectory}/{scan_number}/{instrument}-{scan_number}-{detector}'
+Visit Template: /tmp/{instrument}/data/{year}/{visit}
+Scan Template: {subdirectory}/{instrument}-{scan_number}
+Detector Template: {subdirectory}/{scan_number}/{instrument}-{scan_number}-{detector}
+DB Scan Number: 0
+File Scan Number: 122
+Tracker File Extension: None
+```
+
+### Configurations
+
+The `configuration` subcommand corresponds to the `configurations` graphql
+query. If no beamlines are included in the command, all configurations are
+returned, otherwise only those matching the given beamlines are returned
+(possible none if no beamlines match).
+
+#### List all configurations
+```bash
+$ numtracker client configuration
+Beamline: i11
+    Visit Template: ...
+    Scan Template: ...
+    Detector Template: ...
+    DB Scan Number: ...
+    File Scan Number: ...
+    Tracker File Extension: ...
+Beamline: i22
+    Visit Template: ...
+    Scan Template: ...
+    Detector Template: ...
+    DB Scan Number: ...
+    File Scan Number: ...
+    Tracker File Extension: ...
+Beamline: b21
+    Visit Template: ...
+    Scan Template: ...
+    Detector Template: ...
+    DB Scan Number: ...
+    File Scan Number: ...
+    Tracker File Extension: ...
+```
+
+#### Filter configurations
+```bash
+$ numtracker client configuration -b i22
+Beamline: i22
+    Visit Template: ...
+    Scan Template: ...
+    Detector Template: ...
+    DB Scan Number: ...
+    File Scan Number: ...
+    Tracker File Extension: ...
+```
+
+### Visit Directory
+
+The `visit-directory` subcommand is a reduced version of the `paths` graphql
+query. It only returns the directory path.
+
+```bash
+$ numtracker client visit-directory i22 cm12345-6
+/tmp/i22/data/2025/cm12345-6/
+```
+
 [_graphiql]:https://github.com/graphql/graphiql/
 [_jq]:https://jqlang.github.io/jq/

README.md

@@ -1,5 +1,6 @@
 fn main() {
     println!("cargo::rerun-if-changed=migrations");
+    println!("cargo::rerun-if-changed=queries");
     built::write_built_file().expect("Failed to write build time information");
     // Force the application to be rebuilt after committing to ensure build info is up to date
     println!("cargo::rerun-if-changed=.git/refs");

build.rs

@@ -31,4 +31,4 @@ spec:
   lifecycle: production
   owner: group:data-acquisition
   definition:
-    $text: ./static/service_schema
+    $text: ./static/service_schema.graphql

catalog-info.yaml

@@ -0,0 +1,11 @@
+query ConfigurationQuery($instrument: [String!]) {
+  configurations(instrumentFilters: $instrument) {
+    instrument
+    scanTemplate
+    directoryTemplate
+    detectorTemplate
+    fileScanNumber
+    dbScanNumber
+    trackerFileExtension
+  }
+}

queries/configuration.graphql

@@ -0,0 +1,16 @@
+mutation ConfigureMutation($instrument: String!, $scan: String, $directory: String, $detector: String, $scan_number: Int, $ext: String) {
+    configure(instrument: $instrument, config: {
+        scan: $scan,
+        directory: $directory,
+        detector: $detector,
+        scanNumber: $scan_number,
+        trackerFileExtension: $ext
+    }) {
+        directoryTemplate
+        scanTemplate
+        detectorTemplate
+        dbScanNumber
+        fileScanNumber
+        trackerFileExtension
+    }
+}

queries/configure.graphql

@@ -0,0 +1,5 @@
+query PathQuery($instrument: String!, $instrumentSession: String!) {
+    paths(instrument: $instrument, instrumentSession: $instrumentSession) {
+        path
+    }
+}

queries/path.graphql

@@ -0,0 +1,49 @@
+use clap::{Parser, Subcommand};
+use url::Url;
+
+#[derive(Debug, Parser)]
+pub struct ClientOptions {
+    #[clap(flatten)]
+    pub connection: ConnectionOptions,
+    #[clap(subcommand)]
+    pub command: ClientCommand,
+}
+
+#[derive(Debug, Parser)]
+pub struct ConnectionOptions {
+    #[clap(long, short = 'H', env = "NUMTRACKER_SERVICE_HOST")]
+    pub host: Option<Url>,
+    #[clap(long, env = "NUMTRACKER_AUTH_HOST")]
+    pub auth: Option<Url>,
+}
+
+#[derive(Debug, Subcommand)]
+pub enum ClientCommand {
+    /// Query existing configurations
+    Configuration {
+        #[clap(short)]
+        beamline: Option<Vec<String>>,
+    },
+    /// Update or add new configurations
+    Configure {
+        beamline: String,
+        #[clap(flatten)]
+        config: ConfigurationOptions,
+    },
+    /// Query for templated data
+    VisitDirectory { beamline: String, visit: String },
+}
+
+#[derive(Debug, Parser)]
+pub struct ConfigurationOptions {
+    #[clap(long)]
+    pub directory: Option<String>,
+    #[clap(long)]
+    pub scan: Option<String>,
+    #[clap(long, alias = "det")]
+    pub detector: Option<String>,
+    #[clap(long = "number")]
+    pub scan_number: Option<i64>,
+    #[clap(long, alias = "ext")]
+    pub tracker_file_extension: Option<String>,
+}