ma-core 0.10.10

DIDComm service library: inboxes, outboxes, DID document publishing, and transport abstraction
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135

//! Command-line argument struct for ma-core-based binaries.
//!
//! Flatten [`MaArgs`] into your own `#[derive(Parser)]` struct so that every
//! binary in the ma ecosystem accepts a consistent set of arguments:
//!
//! ```rust,ignore
//! use clap::Parser;
//! use ma_core::config::MaArgs;
//!
//! const MA_DEFAULT_SLUG: &str = "panteia";
//!
//! #[derive(Parser)]
//! struct Cli {
//!     #[command(flatten)]
//!     ma: MaArgs,
//! }
//!
//! fn main() -> anyhow::Result<()> {
//!     let cli = Cli::parse();
//!     let config = ma_core::config::Config::from_args(&cli.ma, MA_DEFAULT_SLUG)?;
//!     config.init_logging()?;
//!     Ok(())
//! }
//! ```

use std::path::PathBuf;

use clap::Args;

/// Standard ma-core CLI arguments.
///
/// Add these to your binary with `#[command(flatten)]`.
///
/// `MA_CONFIG` and `MA_SLUG` are the only statically-named environment
/// variables; all other fields are resolved dynamically in
/// [`super::Config::from_args`] using the binary's compile-time `MA_DEFAULT_SLUG`
/// constant as a prefix (e.g. `MA_PANTEIA_LOG_LEVEL`), with a plain
/// `MA_LOG_LEVEL`-style fallback.
#[derive(Args, Debug, Clone, Default)]
pub struct MaArgs {
    /// Path to the YAML config file. Overrides the slug-derived default
    /// (`XDG_CONFIG_HOME/ma/<slug>.yaml`).
    ///
    /// Environment variable: `MA_CONFIG`
    #[arg(long, env = "MA_CONFIG")]
    pub config: Option<PathBuf>,

    /// Runtime slug. Overrides `MA_DEFAULT_SLUG` for file naming
    /// (`<slug>.yaml`, `<slug>.bin`, `<slug>.log`) only.
    ///
    /// The env-var prefix `MA_<MA_DEFAULT_SLUG>_*` is always determined by
    /// the compile-time constant — this value does **not** change the prefix.
    ///
    /// Environment variable: `MA_SLUG`
    #[arg(long, env = "MA_SLUG")]
    pub slug: Option<String>,

    /// Log level for the log file (`trace`, `debug`, `info`, `warn`, `error`).
    ///
    /// Resolved via `MA_<MA_DEFAULT_SLUG>_LOG_LEVEL` → `MA_LOG_LEVEL` → YAML
    /// → default `"info"`.
    #[arg(long)]
    pub log_level: Option<String>,

    /// Path to the log file. Defaults to `XDG_DATA_HOME/ma/<slug>.log`.
    ///
    /// Resolved via `MA_<MA_DEFAULT_SLUG>_LOG_FILE` → `MA_LOG_FILE` → YAML
    /// → XDG default.
    #[arg(long)]
    pub log_file: Option<PathBuf>,

    /// Log level for stdout output (`trace`, `debug`, `info`, `warn`, `error`).
    ///
    /// Resolved via `MA_<MA_DEFAULT_SLUG>_LOG_LEVEL_STDOUT` →
    /// `MA_LOG_LEVEL_STDOUT` → YAML → default `"warn"`.
    #[arg(long)]
    pub log_level_stdout: Option<String>,

    /// Positive DID cache TTL in seconds.
    ///
    /// Set to `0` to disable caching successful DID resolutions.
    /// Resolved via `MA_<MA_DEFAULT_SLUG>_DID_RESOLVER_POSITIVE_TTL_SECS` →
    /// `MA_DID_RESOLVER_POSITIVE_TTL_SECS` → YAML → default `60`.
    #[arg(long)]
    pub did_resolver_positive_ttl_secs: Option<u64>,

    /// Negative DID cache TTL in seconds.
    ///
    /// Set to `0` to disable caching failed DID resolutions.
    /// Resolved via `MA_<MA_DEFAULT_SLUG>_DID_RESOLVER_NEGATIVE_TTL_SECS` →
    /// `MA_DID_RESOLVER_NEGATIVE_TTL_SECS` → YAML → default `10`.
    #[arg(long)]
    pub did_resolver_negative_ttl_secs: Option<u64>,

    /// Path to the encrypted secret bundle file.
    /// Defaults to `XDG_CONFIG_HOME/ma/<slug>.bin`.
    ///
    /// Resolved via `MA_<MA_DEFAULT_SLUG>_SECRET_BUNDLE` →
    /// `MA_SECRET_BUNDLE` → YAML → XDG default.
    #[arg(long)]
    pub secret_bundle: Option<PathBuf>,

    /// Passphrase to unlock the secret bundle.
    ///
    /// In headless configs this is stored in cleartext in the YAML file.
    /// Prefer setting via environment variable rather than CLI to avoid
    /// shell history exposure.
    ///
    /// Resolved via `MA_<MA_DEFAULT_SLUG>_SECRET_BUNDLE_PASSPHRASE` →
    /// `MA_SECRET_BUNDLE_PASSPHRASE` → YAML.
    #[arg(long)]
    pub secret_bundle_passphrase: Option<String>,

    /// Kubo RPC API URL. Defaults to `http://127.0.0.1:5001`.
    ///
    /// Resolved via `MA_<MA_DEFAULT_SLUG>_KUBO_RPC_URL` →
    /// `MA_KUBO_RPC_URL` → YAML → default.
    #[arg(long)]
    pub kubo_rpc_url: Option<String>,

    /// IPNS key alias used in Kubo. Defaults to the slug.
    ///
    /// Resolved via `MA_<MA_DEFAULT_SLUG>_KUBO_KEY_ALIAS` →
    /// `MA_KUBO_KEY_ALIAS` → YAML → slug.
    #[arg(long)]
    pub kubo_key_alias: Option<String>,

    /// Generate a headless config with a fresh secret bundle, write both
    /// files with 0600 permissions, and exit.
    ///
    /// If `--secret-bundle-passphrase` is not provided, a random passphrase
    /// is generated and written into the config file.
    #[arg(long)]
    pub gen_headless_config: bool,
}