Skip to main content

arvo_client/
lib.rs

1//! Talk to Arvo's engine over gRPC.
2//!
3//! This is the client side of the
4//! [contract](https://github.com/wjpin84/arvo-engine-api): the stubs
5//! generated from its services, how to find the engine running for this
6//! user, and the token each service takes. The types the stubs carry are
7//! `arvo-api`, re-exported under [`proto`] so a call site names one path
8//! whether it wants a stub or a shape.
9//!
10//! # Finding the engine
11//!
12//! The engine serves on loopback and writes where it is into the user's app
13//! data directory. [`discovery`] reads that: the address, whether the engine
14//! at it is still answering, and the two tokens.
15//!
16//! # Two tokens
17//!
18//! Which token a service takes is a property of the service, not of the
19//! call. The **research token**, from `engine.json`, reaches the `Research`
20//! service and nothing else: an agent or a script holding it can read
21//! findings and run studies, and cannot fetch, trade, share, import or name
22//! a credential. The **control token**, from `control.json`, reaches every
23//! other service, which is where a person's decisions live. [`request`] puts
24//! either one on a call.
25//!
26//! # A call
27//!
28//! ```no_run
29//! use arvo_client::{discovery, proto, request};
30//! use proto::common::Empty;
31//! use proto::services::research_client::ResearchClient;
32//!
33//! # #[tokio::main] async fn main() -> Result<(), Box<dyn std::error::Error>> {
34//! let engine = discovery::running(&discovery::default_root()?).ok_or("start arvo-engine first")?;
35//! let mut research = ResearchClient::connect(engine.endpoint()).await?;
36//! let listed = research.list_strategies(request(&engine.token, Empty {})?).await?.into_inner();
37//! for strategy in listed.strategies {
38//!     println!("{}: {}", strategy.name, strategy.premise);
39//! }
40//! # Ok(()) }
41//! ```
42//!
43//! A refusal crosses as a gRPC status code, never as a message with an error
44//! field. A study's answer is large; see [`wire::MAX_MESSAGE_BYTES`].
45//!
46//! # The server side
47//!
48//! The same generated module holds the server traits, `research_server::Research`
49//! and the rest. Arvo's engine implements them; so can a test double.
50
51#![warn(missing_docs)]
52
53/// The contract, as this side of the wire uses it.
54///
55/// The services are generated here; every type they carry is generated once,
56/// in `arvo-api`, and re-exported below so a call site names one path whether
57/// it wants a stub or a shape.
58pub mod proto {
59    pub use crate::generated::services;
60
61    pub use arvo_api::{common, market, platform, portfolio, research, session};
62}
63
64mod generated;
65
66pub mod discovery;
67pub mod wire;
68
69mod error;
70pub use error::CommandError;
71
72/// `message`, carrying `token` the way the engine admits it.
73///
74/// Which token is the caller's business: the research token for the
75/// `Research` service, the control token for everything else. A token from
76/// the wrong file is refused as `Unauthenticated`, not as a bad request.
77///
78/// # Errors
79///
80/// A token that is not printable ASCII, which the engine never writes.
81pub fn request<T>(
82    token: &str,
83    message: T,
84) -> Result<tonic::Request<T>, tonic::metadata::errors::InvalidMetadataValue> {
85    let mut request = tonic::Request::new(message);
86    request.metadata_mut().insert("authorization", format!("Bearer {token}").parse()?);
87    Ok(request)
88}