audit our examples #1929

b5 · 2024-01-05T18:17:45Z

a user on our discord has pointed out that our examples need a cleanup to match recent changes. We should do an audit of examples & make sure they're up to date by confirming each example works as described.

The text was updated successfully, but these errors were encountered:

s2dd · 2024-01-05T19:08:41Z

/iroh/iroh/examples/collection has hardcoded

    // print the ticket, containing all the above information
    println!("in another terminal, run:");
    println!("\t$ cargo run -- get --ticket {}", ticket);
    // wait for the node to finish, this will block indefinitely
    // stop with SIGINT (ctrl+c)
    node.await?;

where i today need use console and there issue blob get <ticket> produced from example.

s2dd · 2024-01-05T19:14:40Z

Stated in the README.md
"At the top of each example file is a comment describing how to run the example."
more then often outdated ...

ramfox · 2024-01-05T20:32:57Z

for /iroh-net/examples/magic.rs specifically:
I believe when a user looks at an example called "magic" they believe that it's meant to magically connect via just node_id, but I'm pretty sure the intention here is to just show how to use MagicEndpoint

we should:

write docs that talk about the intention of the example
mention that if you supply a direct addr only on connect, you may not be able to connect if you require any hole-punching

for the listen command:

print out all of our known addrs
print out all of our derp urls
print out what command should be run in another terminal to connect correctly
allow overrides for bind-port and derp-url are "global", but should really be moved to listen (since the connect command has a derp-url parameter that isn't global as well)

for the connect command:

don't allow the command to run if you don't have one of addr or derp_url

However, if we are supposed to show that we can magically connect via just node id, we need to add default derp_urls to the connect command.

edit:
we decided that we are better off showing an example that is simpler & does not allow for much configuration. mentioned below: #1929 (comment)

s2dd · 2024-01-05T20:37:41Z

if no derp_url use default_derp_url

besides node-id , addr , maybe a ticket with derp_urlembeded = calling-card

ramfox · 2024-01-05T20:52:49Z

if no derp_url use default_derp_url

besides node-id , addr , maybe a ticket with derp_urlembeded = calling-card

if the examples are there to educate someone about what MagicEndpoint does and how to start understanding/coding with it, then adding a default_derp_url and wrapping everything in a ticket is depriving the dev of learning how to use MagicEndpoint

so I'm not sure I would want to hide these here. For any example in the github.com/n0-computer/iroh-examples repo, I think we should definitely use tickets and defaults.

just an opinion ¯_(ツ)_/¯ not married to it

s2dd · 2024-01-05T21:20:11Z

i am in favor of dynamic derps in calling-cards and tickets
find for my use-cases need own derp in open but closed for the wild p2p's
having default hardcoded derps is fine but if --derp-url is provided should take precedence ?

so its like if You don't need it You have it ...

s2dd · 2024-01-08T04:41:52Z

@b5 i can not find /iroh/examples/stream.rs mentioned above

s2dd · 2024-01-08T04:53:03Z

@b5 but there is a `/iroh/examples/rpc.rs

that i can not get to work ...

"
//! An example that runs an iroh node that can be controlled via RPC.
//!
//! Run this example with
//! $ cargo run --example rpc
//! Then in another terminal, run any of the normal iroh CLI commands, which you can run from
//! cargo as well:
//! $ cargo run node stats
//! The node stats command will reach out over RPC to the node constructed in the example
"
after run --example rpc
and then issue run node stats i get

Error: rpc connect

Caused by:
    iroh is not running, please start it

s2dd · 2024-01-08T11:51:30Z

https://iroh.computer/docs/quickstart

when try start node B per documentation
$ export IROH_DATA_DIR=./
$ iroh start --rpc-port 1111

no joy

configuration option flag --rpc-port do not exist in
[package]
name = "iroh"
version = "0.12.0"

maybe reference version in documentation´s

i see there is auto for 0.12.0
$ iroh start

RPC port 4919 already in use, switching to random port

but how to start console for node B port ?

need run node B on other ip for example

s2dd · 2024-01-08T12:18:08Z

my comment so far is code is very clean but documentation for version examples ++ is lagging.

ramfox · 2024-01-20T01:17:13Z

TODO:

add "fetch" side of the simple examples for hello_world & collection @ramfox
/iroh/examples/dump-blob-fsm.rs should remove references to iroh-net (& use direct quic connections instead), and be moved to iroh-bytes @flub
/iroh/examples/dump-blob-stream.rs should do the same @flub
/iroh-net/examples/magic.rs should be largely simplified, taking out any CLI / clap, and expecting the direct addrs and derp URL as arguments (not supplied by flags)

## Description Fixes incorrect information in our `iroh/examples` Also adds an example that shows the most basic way to use iroh to fetch content. related to #1929 ## Notes & open questions Unfortunately, we don't seem to have very simple APIs for fetching (that isn't just exporting the content to an external path). Working through this. Also adds: - `BlobDownloadProgress` - this takes a stream of `DownloadProgress` and puts it into a form that will poll the stream by calling `finish` - adjusts the `blob_download0` function to not eat certain errors ## Change checklist - [x] Self-review. - [x] Documentation updates if relevant.

## Description closes #1929 ### `provide-bytes` This example adds either a single blob or collection to the database and provides it. It gives instructions on how to run the fetch side of the example for `fetch-fsm` and `fetch-stream`. We could make this example more "advanced" by having the user provide a path & serve the blob or collection of that content, but I wanted to keep its simple at first. ### `fetch-fsm` This example fetches a blob or collection using the `get` finite state machine directly, printing the contents to the terminal. ### `fetch-stream` This example fetches a blob or collection using a helper function to turn the `get` finite state machine into a stream. It prints the contents to the terminal. ## Change checklist - [x] Self-review. - [x] Documentation updates if relevant. - [ ] Tests if relevant.

## Description Fixes incorrect information in our `iroh/examples` Also adds an example that shows the most basic way to use iroh to fetch content. related to n0-computer#1929 ## Notes & open questions Unfortunately, we don't seem to have very simple APIs for fetching (that isn't just exporting the content to an external path). Working through this. Also adds: - `BlobDownloadProgress` - this takes a stream of `DownloadProgress` and puts it into a form that will poll the stream by calling `finish` - adjusts the `blob_download0` function to not eat certain errors ## Change checklist - [x] Self-review. - [x] Documentation updates if relevant.

## Description closes n0-computer#1929 ### `provide-bytes` This example adds either a single blob or collection to the database and provides it. It gives instructions on how to run the fetch side of the example for `fetch-fsm` and `fetch-stream`. We could make this example more "advanced" by having the user provide a path & serve the blob or collection of that content, but I wanted to keep its simple at first. ### `fetch-fsm` This example fetches a blob or collection using the `get` finite state machine directly, printing the contents to the terminal. ### `fetch-stream` This example fetches a blob or collection using a helper function to turn the `get` finite state machine into a stream. It prints the contents to the terminal. ## Change checklist - [x] Self-review. - [x] Documentation updates if relevant. - [ ] Tests if relevant.

ramfox added this to the v0.13.0 milestone Jan 11, 2024

ramfox assigned ramfox and flub Jan 22, 2024

ramfox added docs Improvements or additions to documentation c-iroh-net c-iroh-bytes c-iroh labels Jan 22, 2024

ramfox mentioned this issue Jan 23, 2024

fix(examples): Adjust and add examples #1968

Merged

2 tasks

ramfox mentioned this issue Feb 1, 2024

move some examples down to iroh-bytes #1981

Merged

3 tasks

ramfox closed this as completed in #1981 Feb 1, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

audit our examples #1929

audit our examples #1929

b5 commented Jan 5, 2024 •

edited by ramfox

Loading

s2dd commented Jan 5, 2024 •

edited

Loading

s2dd commented Jan 5, 2024

ramfox commented Jan 5, 2024 •

edited

Loading

s2dd commented Jan 5, 2024

ramfox commented Jan 5, 2024

s2dd commented Jan 5, 2024

s2dd commented Jan 8, 2024

s2dd commented Jan 8, 2024

s2dd commented Jan 8, 2024 •

edited

Loading

s2dd commented Jan 8, 2024

ramfox commented Jan 20, 2024 •

edited

Loading

audit our examples #1929

audit our examples #1929

Comments

b5 commented Jan 5, 2024 • edited by ramfox Loading

s2dd commented Jan 5, 2024 • edited Loading

s2dd commented Jan 5, 2024

ramfox commented Jan 5, 2024 • edited Loading

s2dd commented Jan 5, 2024

ramfox commented Jan 5, 2024

s2dd commented Jan 5, 2024

s2dd commented Jan 8, 2024

s2dd commented Jan 8, 2024

s2dd commented Jan 8, 2024 • edited Loading

s2dd commented Jan 8, 2024

ramfox commented Jan 20, 2024 • edited Loading

b5 commented Jan 5, 2024 •

edited by ramfox

Loading

s2dd commented Jan 5, 2024 •

edited

Loading

ramfox commented Jan 5, 2024 •

edited

Loading

s2dd commented Jan 8, 2024 •

edited

Loading

ramfox commented Jan 20, 2024 •

edited

Loading