Get help getting started

[mattgreg]

Thank you for learning to build with Ockam.

We are here to help.

If you get lost, find a bug, or have a question on the getting started guide workflow reach out in this discussion thread!

[fimbault]

Great work. It works fine and it's almost clear for me.
The hub itself is just a TCP address (just like in example 7), but having an idea on the architecture of the RemoteForwarder would help.
For instance, after having made it work through https://hub.ockam.network, trying through a local address triggers a NoSuchWorker error (I'm just trying to understand what's going on, of course it's fine for ockam to provide its hosted service). Providing a small example would help.

[mrinalwadhwa]

@fimbault thank you for stepping through the guide. That it invaluable feedback ... we struggled with the balance of whether to expose the RemoteForwarder logic in the examples or to hide it in the lib.

We're working on an update to the guide, I'll try to add a more detailed explanation about it in that next version.

In the meantime here are the two workers involved in making that work, please have a look and let us know if you have questions.

Rust RemoteForwarder worker code that is invoked by the examples.
https://github.com/ockam-network/ockam/blob/develop/implementations/rust/ockam/ockam/src/remote_forwarder.rs

Elixir code that is running on a cloud node created by the hub, is also a worker, written in Elixir
https://github.com/ockam-network/ockam/blob/develop/implementations/elixir/ockam/ockam_hub/lib/hub/service/alias.ex

[jjscheel]

Here are my general comments:

• I made it through everything without finding any technical errors. Hats off to the team!
• I think the document is incredibly well written and easy to follow. I especially appreciate the way examples are set up, detailed, and then specific points are highlighted after the code is shown.
• The routing flows and technical details included on each message were very helpful to explain the "how".
• The technique of "touching" a file and then editing it, can likely be consolidated into "Create the new file examples/ with this source:".
• There's some inconsistency in Sub-section naming. Some titles start each word with an Upper case, others only the first word.
• My sense is that more time has been put on the introductory items and the level of technical explanation tailed off in the later modules. Revisiting them in general would be good.

Here are my technical comments:

1. The reference to get started (which also links to 00. Setup) is confusing on the first page. I'd remove the first link and leave the list as it stands.
2. In the 00. Setup document, when installing Rust, it's probably worth mentioning that the default installation is fine and remind them to verify that Cargo ($HOME/.cargo/bin) has been added to their PATH (they might just need to refresh as the .bashrc sources the ~/.cargo/env file).
3. In the 00. Setup document, in the "Creating a new Cargo package" section, I appreciated the text about the coming examples. What was not clear (yet) was whether these would create new directories and where. An additional explanation and maybe even directory structure (liked the one included after making the library package) would be very helpful.
4. In the 01. Node document, when defining the Node as "an asynchronous execution environment" it might be able to also define it in Unix terms. I suspect that an Ockam Node is actually a Process and that the Workers are threads. This goes to explaining more your definitions of "lightweight" as well as memory addressability.
5. In the 01. Node document, a link to more information on Tokio might be helpful, perhaps to https://tokio.rs/.
6. In the 01. Node document, the "Create a node" section", when one attempts to build the first example, one will fail with the error "error: linker cc not found" if the gcc compiler is not on the system. This dependency should be added to the 00. Setup document. (I suspect this is a result of the script you are using to put rust on the system. Most package managers would have this dependency built in.)
7. In the 01. Node document, the "Create a node" section", after the first example run, sample output would be nice, but I can see that you've consistently avoided doing this in lieu of providing message flows in later sections.
8. In the 02. Worker document, the definition of the Workers list: there's a reference to "address" which could use more explanation. If I understand the design, it's like a postal "address" in the sense that it's a unique identification for addressing with the Worker and not like a memory address where information can be written, read, or stored.
9. In the 02. Worker document, the term "Echoer" is a bit awkward. You might consider simply "Echo" or "Repeater".
10. In the 02. Worker document, the "Echoer worker" section, a few additional remarks as to origins of the "Musts" such as the ockam::async_worker attribute would be helpful as well. This would be an excellent way to allow people to dig deeper.
11. In the 02. Worker document, the explanation of the echoer.rs source: an sentence as the need for having "Context" in the worker and it's role in providing useful information about the worker such as it's address.
12. In the 03. Routing and the 04. Routing over many hops documents: the message flow graphics show the "Hello Ockam!" as the payload, but the console output from the hop nodes print "Any Message". I recognize that you want that node to route generically, but wonder if for this example we should interrogate the type of the message and print the string if it indeed is such. A first look at this suggests it's not something immediately implementable at the hop.rs node, but tied to the message.rs implementation in ockam_core.
13. In the 05. Secure Channel document, last paragraph of the introductory section: a reminder that the project is defined in Cargo.toml file would be helpful.
14. In the 05. Secure Channel document, the "App worker" section: extending "Like our previous examples, we'll..." to "Like our previous example 02. Worker, we'll..." would provide a nice comparison for folks who want to look at code differences.
15. In the 05. Secure Channel. Secure Channel document, the "App worker" section: the Cargo console output has become more noisy in this example. The base messages are still there and the value of having the new information to help with new components is good. I just wonder if you can show messages more reflective of the "Channel Setup" purple box in the "Message Flow" section which follows.
16. In the 05. Secure Channel document, the "Message Flow" section: would benefit from a textual description describing the upfront key exchange and then the message flows. I suspect the components of "channel_initiator, channel_responder, and channel_listener are generic constructs which might evolve over time with newer/different protocols. Given the architected design point, this would be a great way to highlight how the app will be shielded from internal flow changes with different protocols.
17. In the 06. Secure Channel over many hops document, "App worker" section: if the hop.rs code was extended to detect and print String text, the noted change in the console output would drive home that the node cannot decipher the message.
18. In the 06. Secure Channel over many hops document, "Message Flow" section: the lines from "channel_initiator" through "channel_responder" and back appears as it goes directly from one to the other, when in fact it does stop at the hop nodes per the console output. I'd recommend that these be broken into their respective lines. (If this change makes the graph too busy by taking every hop through an initiator/listener pair, I still think this provides value. But, I understand the trade-off here of accuracy and understandability.)
19. In the 07. Routing over a transport document: an explanation of when, why, or how this example is pertinent would make the example stronger. Additionally, comments as to supported transports today and in the future might be good.
20. In the 07. Routing over a transport document, the "Run" section: this section could really benefit from more explanation. In particular, it should be noted that the two commands will require separate windows on the same system to run and that the "responder" will not terminate. A comparison back to the similar examples in 02. Worker and 05. Secure Channel would make this excellent.
    21.In the 07. Routing over a transport document, the "Message Flow" section: textual explanation and comparisons to previous flows would strengthen the document.
21. 08. Routing over many transport hops and 09. Secure Channel over many transport hops: similar comments to 20 and 21. The interesting question for these examples is how to show that the intermediate nodes get "touched". The code on those nodes don't really make that obvious at this time.

I also found a couple typos or minimal updates I'll submit separately in the coming days.

[mrinalwadhwa]

Extremely helpful feedback!! Thank you @jjscheel 🙏