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
//! Talk to Arvo's engine over gRPC.
//!
//! This is the client side of the
//! [contract](https://github.com/wjpin84/arvo-engine-api): the stubs
//! generated from its services, how to find the engine running for this
//! user, and the token each service takes. The types the stubs carry are
//! `arvo-api`, re-exported under [`proto`] so a call site names one path
//! whether it wants a stub or a shape.
//!
//! # Finding the engine
//!
//! The engine serves on loopback and writes where it is into the user's app
//! data directory. [`discovery`] reads that: the address, whether the engine
//! at it is still answering, and the two tokens.
//!
//! # Two tokens
//!
//! Which token a service takes is a property of the service, not of the
//! call. The **research token**, from `engine.json`, reaches the `Research`
//! service and nothing else: an agent or a script holding it can read
//! findings and run studies, and cannot fetch, trade, share, import or name
//! a credential. The **control token**, from `control.json`, reaches every
//! other service, which is where a person's decisions live. [`request`] puts
//! either one on a call.
//!
//! # A call
//!
//! ```no_run
//! use arvo_client::{discovery, proto, request};
//! use proto::common::Empty;
//! use proto::services::research_client::ResearchClient;
//!
//! # #[tokio::main] async fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let engine = discovery::running(&discovery::default_root()?).ok_or("start arvo-engine first")?;
//! let mut research = ResearchClient::connect(engine.endpoint()).await?;
//! let listed = research.list_strategies(request(&engine.token, Empty {})?).await?.into_inner();
//! for strategy in listed.strategies {
//! println!("{}: {}", strategy.name, strategy.premise);
//! }
//! # Ok(()) }
//! ```
//!
//! A refusal crosses as a gRPC status code, never as a message with an error
//! field. A study's answer is large; see [`wire::MAX_MESSAGE_BYTES`].
//!
//! # The server side
//!
//! The same generated module holds the server traits, `research_server::Research`
//! and the rest. Arvo's engine implements them; so can a test double.
/// The contract, as this side of the wire uses it.
///
/// The services are generated here; every type they carry is generated once,
/// in `arvo-api`, and re-exported below so a call site names one path whether
/// it wants a stub or a shape.
pub use CommandError;
/// `message`, carrying `token` the way the engine admits it.
///
/// Which token is the caller's business: the research token for the
/// `Research` service, the control token for everything else. A token from
/// the wrong file is refused as `Unauthenticated`, not as a bad request.
///
/// # Errors
///
/// A token that is not printable ASCII, which the engine never writes.