cuprated: embeddable node library with Node::launch()

[redsh4de]

What

Extracts cuprated into an embeddable library (lib.rs/main.rs pattern). Takes inspiration from the API proposed in #554

Closes #516

Note to reviewers: This does not implement graceful shutdown / panic removal yet, those have been deferred to #585. For the final state with all changes, skip to #590

Why

To enable embedding the node in other applications

Where

• cuprated:
  • Cargo.toml - explicit [lib] + [[bin]] targets
  • lib.rs - new: Node struct, NodeContext for shared state, Node::launch(), public service handles
  • main.rs - simplified to CLI wrapper calling Node::launch()
  • commands.rs - actor pattern rewrite: CommandHandle with mpsc/oneshot, send_command() API
  • config.rs - decoupled from CLI args, find_config() returns Result<Option<Config>>, removed process::exit from library code
  • blockchain/syncer.rs - SyncNotify renamed to SyncState
  • blockchain/interface.rs - free functions + statics (COMMAND_TX, BLOCKS_BEING_HANDLED) converted to BlockchainManagerHandle struct with owned channel + lock
  • version.rs - add Default impl (thanks clippy)
  • Removed mutable statics in favor of NodeContext for multi-instance support
• consensus/fast-sync:
  • Removed global FAST_SYNC_HASHES static
  • set_fast_sync_hashes removed; fast_sync_stop_height and validate_entries now take hashes as a parameter from NodeContext

How

Node::launch(config) in lib.rs handles all initialization and returns a Node with service handles that serve as the API to the embeder:

pub struct Node {
    pub context: BlockchainContextService,
    pub blockchain: BlockchainReadHandle,
    pub txpool: TxpoolReadHandle,
    pub clearnet: NetworkInterface<ClearNet>,
    pub tor: Option<oneshot::Receiver<NetworkInterface<Tor>>>,
    pub syncer: SyncerHandle,
    pub command: CommandHandle,
}

The previous mutable statics were moved into NodeContext, making the node safe to run multiple times in a single process.

pub struct NodeContext {
    pub network: Network,
    pub fast_sync_hashes: &'static [[u8; 32]], /// was static
    pub reorg_lock: Arc<RwLock<()>>, // was static
    pub blockchain_manager: BlockchainManagerHandle, // was composed of statics
    pub blockchain_read: BlockchainReadHandle,
    pub blockchain_context: BlockchainContextService,
    pub txpool_read: TxpoolReadHandle,
    pub syncer: SyncerHandle,
    pub start_instant: std::time::SystemTime,
    pub start_instant_unix: u64,
}

BlockchainManagerHandle replaces the COMMAND_TX and BLOCKS_BEING_HANDLED statics from interface.rs, wrapping them into a struct with new(), is_block_being_handled(), and handle_incoming_block() methods.

The Tor interface arrives via oneshot after sync, similar to the dandelion.rs pattern.

[sneurlax]

you should try and return something like Result<Self, NodeInitError> rather than panicking

I don't get the difference between or relative purposes of Node and NodeContext. Which should be used for what?

with dry_run_check calling std::process::exit(code), won't an embedder calling config.dry_run_check() get their process killed?

nit but SyncState renamed unnecessarily imo

there's no way to shut it down?

I like main.rs after this tho. I like CommandHandle, get_fast_sync_hashes, BlockchainManagerHandle. not an in depth review but these things stood out to me in a once-over and some tangential reading to try and understand the changes

[redsh4de]

you should try and return something like Result<Self, NodeInitError> rather than panicking

Deferred this to the shutdown PRs - they depend on this branch so they carry everything over (https://github.com/Cuprate/cuprate/pull/585/changes#diff-d448bb1addb0153e0d62b48a7e6531f9988ea8f1846ab783540eaf9f2c87d87fR159)

I don't get the difference between or relative purposes of Node and NodeContext. Which should be used for what?

Node is meant to be the public facing API that the embedder receives and can interact with the node
NodeContext is meant to be the internal global context, replaces statics. Some things in each struct overlap but i prefer the granularity for the two seperate domains

Maybe there could be a better name for each struct so its self-documenting?

with dry_run_check calling std::process::exit(code), won't an embedder calling config.dry_run_check() get their process killed?

Yeah, good call

nit but SyncState renamed unnecessarily imo

It was a transitive change as i was also planning to add current sync target height to the struct, so the embedder can potentially create progress UIs/bars etc, got sidetracked though

there's no way to shut it down?

Ty, added shutdown function to #585 (https://github.com/Cuprate/cuprate/pull/585/changes#diff-d448bb1addb0153e0d62b48a7e6531f9988ea8f1846ab783540eaf9f2c87d87fR342-R344)

[sneurlax]

you should try and return something like Result<Self, NodeInitError> rather than panicking

Deferred this to the shutdown PRs - they depend on this branch so they carry everything over (https://github.com/Cuprate/cuprate/pull/585/changes#diff-d448bb1addb0153e0d62b48a7e6531f9988ea8f1846ab783540eaf9f2c87d87fR159)

I don't get the difference between or relative purposes of Node and NodeContext. Which should be used for what?

Node is meant to be the public facing API that the embedder receives and can interact with the node NodeContext is meant to be the internal global context, replaces statics. Some things in each struct overlap but i prefer the granularity for the two seperate domains

Maybe there could be a better name for each struct so its self-documenting?

with dry_run_check calling std::process::exit(code), won't an embedder calling config.dry_run_check() get their process killed?

Yeah, good call

nit but SyncState renamed unnecessarily imo

It was a transitive change as i was also planning to add current sync target height to the struct, so the embedder can potentially create progress UIs/bars etc, got sidetracked though

there's no way to shut it down?

Ty, added shutdown function to #585 (https://github.com/Cuprate/cuprate/pull/585/changes#diff-d448bb1addb0153e0d62b48a7e6531f9988ea8f1846ab783540eaf9f2c87d87fR342-R344)

Gotcha, OK :) sorry for the incomplete review then, glad to hear most of those issues are resolved by later PRs

[SyntheticBird45]

cancelling workflow because this is some doc nits, let's think a little about our carbon footprint.

[redsh4de]

Think this is the last change i want to make here, didn't like how SyncNotify/State effectively functions as a handle without it being named such, reduces the mental load imo

Also added target_height to the handle so that embedders can create their own progress tracking items and whatnots