From 9884628a9acee5bff855c45b352555fcca657e83 Mon Sep 17 00:00:00 2001 From: Nazmul Idris Date: Sun, 14 Jan 2024 20:41:01 -0800 Subject: [PATCH] Add 2 new tutorials: 1) netcat client & server, 2) tcp chat server --- .vscode/settings.json | 5 +- _includes/featured.html | 20 + _includes/sidebar.html | 29 +- _posts/2019-10-31-fish-scripting-manual.md | 4 +- _posts/2022-02-24-rust-non-binary-tree.md | 10 +- _posts/2022-03-02-rust-grep-cli-app.md | 6 +- _posts/2022-03-12-rust-redux.md | 14 +- _posts/2022-03-12-rust-tokio.md | 9 +- _posts/2022-03-30-rust-proc-macro.md | 113 +++-- _posts/2022-08-04-rust-dsl-part-1.md | 53 +- _posts/2022-11-21-algo-ts-1.md | 6 +- _posts/2022-12-11-algo-ts-2.md | 4 + _posts/2023-02-20-guide-to-nom-parsing.md | 7 +- _posts/2023-08-28-justfile.md | 20 +- _posts/2023-09-17-tuify-clap.md | 18 +- ...2-overcome-your-fear-of-merge-conflicts.md | 13 +- ...-01-13-write-simple-char-server-in-rust.md | 393 +++++++++++++++ .../2024-01-13-write-simple-netcat-in-rust.md | 468 ++++++++++++++++++ _sass/code-block.scss | 2 + _sass/globals.scss | 4 +- _sass/minima/_base.scss | 4 +- assets/chatserver-hero.svg | 108 ++++ assets/chatserver.svg | 86 ++++ assets/netcat-hero.svg | 108 ++++ assets/netcat.svg | 86 ++++ 25 files changed, 1430 insertions(+), 160 deletions(-) create mode 100644 _includes/featured.html create mode 100644 _posts/2024-01-13-write-simple-char-server-in-rust.md create mode 100644 _posts/2024-01-13-write-simple-netcat-in-rust.md create mode 100644 assets/chatserver-hero.svg create mode 100644 assets/chatserver.svg create mode 100644 assets/netcat-hero.svg create mode 100644 assets/netcat.svg diff --git a/.vscode/settings.json b/.vscode/settings.json index 8bcc5960..26f9a973 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -6,6 +6,7 @@ "dribbble", "DSLs", "firamono", + "giti", "Gjengset", "gothambold", "helveticaneue", @@ -16,7 +17,9 @@ "nadiaidris", "nazmulidris", "Ndot", + "netcat", "qself", + "rtelnet", "stackoverflow", "strikethrough", "toolkits", @@ -24,4 +27,4 @@ "vtable", "wght" ] -} +} \ No newline at end of file diff --git a/_includes/featured.html b/_includes/featured.html new file mode 100644 index 00000000..7260f1f6 --- /dev/null +++ b/_includes/featured.html @@ -0,0 +1,20 @@ + +
+

+🌟 Please star the +r3bl-open-core repo. + +You can get lots of useful Rust command line apps from the r3bl-cmdr crate in this repo: +

+ +πŸ“¦ You can install them using cargo install r3bl-cmdr +

+ +

If you would like to get involved in an open source project and like Rust crates, we +welcome your contributions to the +r3bl-open-core repo. +

+
\ No newline at end of file diff --git a/_includes/sidebar.html b/_includes/sidebar.html index b719e21c..32113a87 100644 --- a/_includes/sidebar.html +++ b/_includes/sidebar.html @@ -1,33 +1,42 @@

- Please star and contribute to our Github πŸ™ + Please star our Github and use our apps & libsπŸ™

  • - +
    -

    R3BL TUI

    -

    r3bl_tui

    +

    INSTALL & USE OUR APPS (giti, edi)

    +

    r3bl-cmdr
  • - +
    -

    R3BL Tuify

    -

    r3bl_tuify

    +

    SHORTLINK browser extension

    +

    shortlink
  • - +
    -

    SHORTLINK browser ext

    -

    shortlink

    +

    R3BL TUI LIB

    +

    r3bl_tui

    +
    +     +
    • +
  • + + +
    +

    R3BL TUIFY LIB

    +

    r3bl_tuify
    • diff --git a/_posts/2019-10-31-fish-scripting-manual.md b/_posts/2019-10-31-fish-scripting-manual.md index 3ae98463..31fc0f8c 100644 --- a/_posts/2019-10-31-fish-scripting-manual.md +++ b/_posts/2019-10-31-fish-scripting-manual.md @@ -48,7 +48,7 @@ categories: -Learn how to write fish shell scripts by example. +{%- include featured.html -%} ## Shebang line at the top of your scripts @@ -827,3 +827,5 @@ function timed -d Pass the program or function that you want to execute as an ar echo "⏲ Total runtime: $RUNTIME min ⏲" end ``` + +{%- include featured.html -%} diff --git a/_posts/2022-02-24-rust-non-binary-tree.md b/_posts/2022-02-24-rust-non-binary-tree.md index e8c0c873..ef19d6fd 100644 --- a/_posts/2022-02-24-rust-non-binary-tree.md +++ b/_posts/2022-02-24-rust-non-binary-tree.md @@ -54,10 +54,9 @@ will be allow us to make the tree thread safe and parallel friendly (we will nam > [`r3bl_rs_utils`](https://crates.io/crates/r3bl_rs_utils) crate. > πŸ“œ You can take a look the source code of this thread safe non-binary tree data structure named -> `Arena` in its github [repo](https://github.com/r3bl-org/r3bl-rs-utils). +> `Arena` in its github [repo](https://github.com/r3bl-org/r3bl-open-core/tree/main/utils). -> 🌟 Please star the [`r3bl-open-core` repo](https://github.com/r3bl-org/r3bl-open-core) on github if -> you like it πŸ™. +{%- include featured.html -%} ## Naive approach using weak and strong references @@ -661,7 +660,6 @@ There are functions that make it easy to unwrap things in Rust that are wrapped > [`r3bl_rs_utils`](https://crates.io/crates/r3bl_rs_utils) crate. > πŸ“œ You can take a look the source code of this thread safe non-binary tree data structure named -> `Arena` in its github [repo](https://github.com/r3bl-org/r3bl-rs-utils). +> `Arena` in its github [repo](https://github.com/r3bl-org/r3bl-open-core/tree/main/utils). -> 🌟 Please star the [`r3bl-open-core` repo](https://github.com/r3bl-org/r3bl-open-core) on github if -> you like it πŸ™. +{%- include featured.html -%} diff --git a/_posts/2022-03-02-rust-grep-cli-app.md b/_posts/2022-03-02-rust-grep-cli-app.md index 7c5b5f7e..f6e963a3 100644 --- a/_posts/2022-03-02-rust-grep-cli-app.md +++ b/_posts/2022-03-02-rust-grep-cli-app.md @@ -49,6 +49,8 @@ arguments, stdin, stdout, and piping. > object oriented), please take a look at this [paper](https://arxiv.org/pdf/2307.07069.pdf) > by Will Crichton demonstrating Typed Design Patterns with Rust. +{%- include featured.html -%} + ## Building the main function The first thing we need to do is build the main function. This is where we will be routing @@ -263,6 +265,4 @@ Here are a list of crates that are used in this app. We will explore more complex TUIs built w/ Rust in the future. -> 🌟 Please star the [`r3bl-open-core` repo](https://github.com/r3bl-org/r3bl-open-core) on -> github if you like it πŸ™. If you would like to contribute to it, please click -> [here](https://github.com/r3bl-org/r3bl-open-core/contribute). +{%- include featured.html -%} diff --git a/_posts/2022-03-12-rust-redux.md b/_posts/2022-03-12-rust-redux.md index e3f84d50..f8e4cf36 100644 --- a/_posts/2022-03-12-rust-redux.md +++ b/_posts/2022-03-12-rust-redux.md @@ -50,12 +50,7 @@ tasks. But the reducer functions will be run in sequence (not in separate Tokio > πŸ“œ The source code for the finished Redux library can be found > [here](https://github.com/r3bl-org/r3bl-rs-utils). -> πŸ“¦ You can use this Redux library today by adding -> [`r3bl_rs_utils`](https://crates.io/crates/r3bl_rs_utils/) crate as a dependency in your -> `Cargo.toml`. -> -> 🌟 Please star the [`r3bl-open-core` repo](https://github.com/r3bl-org/r3bl-open-core) on github if -> you like it πŸ™. +{%- include featured.html -%} This article is getting us ready to building more complex TUI apps next using crates like `termion` and `tui`. @@ -638,9 +633,4 @@ Tokio tasks. > information on this library in it's > [`README`](https://github.com/r3bl-org/r3bl-rs-utils/blob/main/README.md#redux) file. -> πŸ“¦ You can use this Redux library today by adding -> [`r3bl_rs_utils`](https://crates.io/crates/r3bl_rs_utils/) crate as a dependency in your -> `Cargo.toml`. -> -> 🌟 Please star the [`r3bl-open-core` repo](https://github.com/r3bl-org/r3bl-open-core) on github if -> you like it πŸ™. +{%- include featured.html -%} diff --git a/_posts/2022-03-12-rust-tokio.md b/_posts/2022-03-12-rust-tokio.md index 6391f757..d9ba5de2 100644 --- a/_posts/2022-03-12-rust-tokio.md +++ b/_posts/2022-03-12-rust-tokio.md @@ -49,6 +49,8 @@ more complex TUI apps next using crates like `termion` and `tui`. > object oriented), please take a look at this [paper](https://arxiv.org/pdf/2307.07069.pdf) > by Will Crichton demonstrating Typed Design Patterns with Rust. +{%- include featured.html -%} + ## Concurrency and async/await, vs parallelism Concurrency is being able to break up your program or function into smaller tasks that can be @@ -691,9 +693,4 @@ Tokio, along w/ the tutorials that are provided on the [Tokio website](https://t We will take this and build upon it further to create a full Redux library in Rust using Tokio [here](https://developerlife.com/2022/03/12/rust-redux/). -> πŸ“¦ For a real implementation of this middleware and Redux library, check out the -> [`r3bl_rs_utils`](https://crates.io/crates/r3bl_rs_utils/) crate. The README has excellent -> documentation on async traits, parallel and concurrent execution, and Tokio. -> -> 🌟 Please star the [`r3bl-open-core` repo](https://github.com/r3bl-org/r3bl-open-core) on github if -> you like it πŸ™. +{%- include featured.html -%} diff --git a/_posts/2022-03-30-rust-proc-macro.md b/_posts/2022-03-30-rust-proc-macro.md index 054e1bd1..269aa578 100644 --- a/_posts/2022-03-30-rust-proc-macro.md +++ b/_posts/2022-03-30-rust-proc-macro.md @@ -16,10 +16,12 @@ categories: - - + - [What are procedural macros](#what-are-procedural-macros) + - [Declarative macros have limitations](#declarative-macros-have-limitations) + - [Summary of proc vs decl macros](#summary-of-proc-vs-decl-macros) + - [Source code examples](#source-code-examples) - [How to add a proc macro lib crate to your existing project](#how-to-add-a-proc-macro-lib-crate-to-your-existing-project) - [Add an internal or core crate](#add-an-internal-or-core-crate) - [What does a syn AST look like?](#what-does-a-syn-ast-look-like) @@ -39,17 +41,20 @@ categories: - [Better implementation that handles generics](#better-implementation-that-handles-generics) - [Using quote!](#using-quote) - [Eg 4 - Derive macro that generates a builder](#eg-4---derive-macro-that-generates-a-builder) + - [Stub out the implementation](#stub-out-the-implementation) + - [Testing the macro](#testing-the-macro) + - [Implementation details](#implementation-details) - [Eg 5 - Attribute macro that adds logging to a function](#eg-5---attribute-macro-that-adds-logging-to-a-function) - [Create entry in lib.rs](#create-entry-in-librs) - [How to parse item?](#how-to-parse-item) - [How to parse args containing attributes for variant 1?](#how-to-parse-args-containing-attributes-for-variant-1) - [How to parse args containing set of identifiers for variant 2?](#how-to-parse-args-containing-set-of-identifiers-for-variant-2) - [Learning resources](#learning-resources) -- [Wrapping up](#wrapping-up) - + ## What are procedural macros + **Procedural macros** are a way for you to extend the Rust compiler and provide plugins that you can use to extend the language. They are really powerful and require some more work to setup in an @@ -64,16 +69,20 @@ declared in the `lib.rs` file). Here are the key benefits of procedural macros: [DSL (domain specific language)](https://developerlife.com/2020/04/04/kotlin-dsl-intro/) like in Kotlin and babel and JavaScript. -> πŸ’‘ **Declarative macros** have many limitations (eg: they can't work with generics) but are easier -> to use. If you have simple use cases they work great, since they are so easy to write. Here are -> some resources to help you w/ learning declarative macros. -> -> 1. [Declarative macros in `r3bl-open-core` repo](https://github.com/r3bl-org/r3bl-open-core/search?q=macro_rules) -> 2. [Declarative macros included in this article's repo (but not covered in this article)](https://github.com/nazmulidris/rust_scratch/blob/main/macros/tests/decl/main.rs) -> 3. [Little book of Rust macros](https://veykril.github.io/tlborm/introduction.html) -> 4. [Great YT video on declarative macros](https://youtu.be/q6paRBbLgNw) +### Declarative macros have limitations + + +For example they can't work with generics. They are easier to write than procedural +macros. If you have simple use cases they work great, since they are so easy to write. +Here are some resources to help you w/ learning declarative macros. + +1. [Declarative macros in `r3bl-open-core` repo](https://github.com/r3bl-org/r3bl-open-core/search?q=macro_rules) +2. [Declarative macros included in this article's repo (but not covered in this article)](https://github.com/nazmulidris/rust_scratch/blob/main/macros/tests/decl/main.rs) +3. [Little book of Rust macros](https://veykril.github.io/tlborm/introduction.html) +4. [Great YT video on declarative macros](https://youtu.be/q6paRBbLgNw) -Here's a summary: +### Summary of proc vs decl macros + | Macro type | Capabilities & limitations | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------ | @@ -82,25 +91,24 @@ Here's a summary: | Procedural - derive | Can't touch token stream of annotated `struct` or `enum`, only add new token stream below; can declare helper attributes | | Procedural - attribute | Like function-like, replaces token stream of annotated item (not just `struct` or `enum`) | -> πŸ“œ **Source code examples** -> -> 1. You can find "real world" examples of both declarative and procedural macros in the -> `r3bl_rs_utils` [crate](https://crates.io/crates/r3bl_rs_utils). -> -> - [proc macros](https://github.com/r3bl-org/r3bl-open-core/tree/main/macro) -> - [decl macros](https://github.com/r3bl-org/r3bl-open-core/search?q=macro_rules) -> -> 2. You can find all the pedagogical examples of macros shown in this article in this -> [repo](https://github.com/nazmulidris/rust_scratch/blob/main/macros/) -> -> 🌟 Please star the [`r3bl-open-core` repo](https://github.com/r3bl-org/r3bl-open-core) on github if -> you like it πŸ™. +### Source code examples + + +1. You can find "real world" examples of both declarative and procedural macros in the + `r3bl-open-core` [repo](https://github.com/r3bl-org/r3bl-open-core). + - [proc macros](https://github.com/r3bl-org/r3bl-open-core/tree/main/macro) + - [decl macros](https://github.com/r3bl-org/r3bl-open-core/search?q=macro_rules) +2. You can find all the pedagogical examples of macros shown in this article in this + [repo](https://github.com/nazmulidris/rust_scratch/blob/main/macros/). + +{%- include featured.html -%} > For more information on general Rust type system design (functional approach rather than > object oriented), please take a look at this [paper](https://arxiv.org/pdf/2307.07069.pdf) > by Will Crichton demonstrating Typed Design Patterns with Rust. ## How to add a proc macro lib crate to your existing project + Rust has two kinds of macros: declarative and procedural. Declarative macros are made using `macro_rules!` inline in your code w/out creating a new lib crate. This article is about procedural @@ -185,6 +193,7 @@ r3bl_rs_utils = "*" > and then runs the test you give that script as an argument. ### Add an internal or core crate + There are situations where you will need to share code between your public crate and your procedural macro crate. In this case you can add an internal or core crate to your project. The shared files @@ -214,6 +223,7 @@ and run `cargo publish` on each and every dependent crate and they will be their crate on crates.io. ## What does a syn AST look like? + Before writing macros, let's talk about how we need to think about things: @@ -299,6 +309,7 @@ the string `"fn foo() -> u32 { 42 }"` using > [dump-syntax](https://github.com/dtolnay/syn/blob/master/examples/dump-syntax/src/main.rs). ## How to write a proc macro of any kind + There are 3 kinds of proc macros. Once you've created a new library crate for them inside your project, you write macros like the ones shown below. @@ -342,6 +353,7 @@ pub fn log_entry_and_exit(args: TokenStream, input: TokenStream) -> TokenStream ``` ### Strategy + The rough idea is that we will have to parse "things" into this `proc_macro2::TokenStream` in order to manipulate them. They can be parsed into this AST from: @@ -364,6 +376,7 @@ In order to do this parsing you have to use the an `ItemFn` AST and then you can work w/ the fields provided by `ItemFn` after that. ### Examples + So here are some examples of what this looks like. @@ -398,6 +411,7 @@ So here are some examples of what this looks like. implement which allows you greater control over the parsing process. ### Writing your own Parse trait impl in different ways + This might not be intuitive, but you can parse the **same** `TokenStream` using various different parsers. You can parse a `TokenStream` as a `Type` or `Ident` or whatever else depending on what you @@ -490,6 +504,7 @@ impl Parse for ManagerOfThingInfo { > team is also quite helpful. ## Eg 1 - Function-like macro that dumps the AST + Let's start our procedural macro journey w/ something very simple. It's a macro that doesn't really emit any token stream. It just prints out the AST of the input as debug. So we won't be using @@ -601,6 +616,7 @@ fn test_proc_macro() { > parse a custom syntax. ## Eg 2 - Function-like macro that parses custom syntax + There are times when you need to create your own syntax or domain specific language. Examples of this are JSX for React. Or DAO generators for a database. In these cases, it's not just about @@ -630,6 +646,7 @@ procedural macro will do the rest. > ideas on custom syntax parsing and creating custom error messages for the compiler. ### Desired syntax and behavior + Let's say that we want to parse a custom syntax like the following, which basically is a declaration of how a manager for the struct `HashMap` should be created. @@ -689,6 +706,7 @@ where ``` ### Implementing the syntax parser + So how would we implement this macro? The first thing is to create a custom parser for the syntax. There are 2 main things we have to do: @@ -792,6 +810,7 @@ impl Parse for ManagerOfThingInfo { ```` ### Implementing the code generator + In this example almost all the work goes into parsing the custom syntax. The code generator we are going to implement is trivial. Here's what it looks like. @@ -834,6 +853,7 @@ pub fn fn_proc_macro_impl(input: TokenStream) ->:TokenStream { `./cargo-watch-one-test.fish test_fn_macro_custom_syntax` ## Eg 3 - Derive macro that adds a method to a struct + We are going to come up w/ a made-up derive macro called `Describe` just for our pedagogical purposes. @@ -843,6 +863,7 @@ purposes. 2. We will then extend this derive macro to handle generics. ### Test for expected output + Here are some simple cases that we should be able to handle in our initial implementation. @@ -882,6 +903,7 @@ fn test_proc_macro() { > `./cargo-watch-one-test.fish test_derive_macro_describe`. ### Watch macro expansion + As we are developing this macro it is really useful not only to have the tests running (in watch mode) but also have the macro expansion running in watch mode. @@ -892,6 +914,7 @@ mode) but also have the macro expansion running in watch mode. > `./cargo-watch-macro-expand-one-test.fish test_derive_macro_describe`. ### Naive implementation + Let's implement this derive macro in a naive way. We won't handle generics, that will happen [later](#better-implementation-that-handles-generics). @@ -1004,6 +1027,7 @@ The `quote!` macro is incredibly powerful and it has a lot of smarts built into when we implement generics support next. ### Better implementation that handles generics + Here's an example of what a simple `Generics` object looks like when generated from `struct Point { ... }`. @@ -1093,6 +1117,7 @@ This might provide some insight into how the `Generics` object itself is structu need to do any of this, since `quote!()` is awesome 🀯. ### Using quote! + Here's a mental model for using `quote!()`: @@ -1160,6 +1185,7 @@ Here are some tips and tricks for using `quote!()`: generating `TokenStream`s manually, and then passing them to `quote!()`. ## Eg 4 - Derive macro that generates a builder + Now that we have seen a relatively simple derive procedural macro, let's look at a more complex one that implements the builder pattern and supports generics. There are two things this macro has to @@ -1177,6 +1203,7 @@ do: > [here](https://github.com/nazmulidris/rust_scratch/blob/main/macros/tests/test_derive_macro_builder.rs). ### Stub out the implementation + We need to make an entry in `lib.rs` for it, like so: @@ -1262,6 +1289,7 @@ pub fn derive_proc_macro_impl(input: proc_macro::TokenStream) -> proc_macro::Tok ``` ### Testing the macro + Here's the test for the derive macro, `test_derive_macro_builder.rs`. They have to cover all the different kinds of structs that we might encounter, some that have generics, some that don't. @@ -1325,6 +1353,7 @@ fn test_proc_macro_generics() { ``` ### Implementation details + Now that we have the skeleton of the entire thing, let's look at some details of how this is implemented. It's worth taking a closer look at the @@ -1403,6 +1432,7 @@ fn add_trait_bounds_to_existing_where_clause_ts( > `./cargo-watch-macro-expand-one-test.fish test_derive_macro_builder` ## Eg 5 - Attribute macro that adds logging to a function + [Attribute procedural macros](https://doc.rust-lang.org/reference/procedural-macros.html#attribute-macros) are very similar to derive procedural macros, with a few key differences. @@ -1446,6 +1476,7 @@ might try out. So let's just make 2 macros. ``` ### Create entry in lib.rs + Let's start by creating an entry in `lib.rs` for these attribute macros. @@ -1505,6 +1536,7 @@ pub fn attrib_proc_macro_impl_2( > `./cargo-watch-one-test.fish test_attribute_macro_logger` ### How to parse item? + How do we parse the `item` parameter? We can use `syn::ItemFn` and `parse_macro_input!()` to parse it into something usable. Here's an example. @@ -1524,6 +1556,7 @@ pub fn attrib_proc_macro_impl_2(args: TokenStream, item: TokenStream) -> TokenSt ``` ### How to parse args containing attributes for variant 1? + How do we parse `args` parameter into something we can use? We can use [`syn::AttributeArgs`](https://docs.rs/syn/latest/syn/type.AttributeArgs.html) along w/ @@ -1621,6 +1654,7 @@ fn key() -> &'static str { ``` ### How to parse args containing set of identifiers for variant 2? + We can also provide our own custom implementation of the `Parse` trait if we want to. Here's an example of this based on syn's @@ -1720,23 +1754,20 @@ pub fn foo() -> &'static str { > [`trace-var`](https://github.com/dtolnay/syn/tree/master/examples/trace-var). ## Learning resources + - Overview - - [Excellent overview video](https://youtu.be/g4SYTOc8fL0) - Books / articles - - [Macro how to](https://doc.rust-lang.org/reference/procedural-macros.html#function-like-procedural-macros) - [Macro how to](https://doc.rust-lang.org/book/ch19-06-macros.html#procedural-macros-for-generating-code-from-attributes) - Workshop - - [Proc macro workshop](https://github.com/dtolnay/proc-macro-workshop/blob/master/README.md) - [Proc macro workshop solutions](https://github.com/jonhoo/proc-macro-workshop) - Technical guides to getting things working - - [Tutorial - Add lib crate for macros](https://dev.to/dandyvica/rust-procedural-macros-step-by-step-tutorial-36n8) - [`lib.rs` restriction](https://users.rust-lang.org/t/how-to-import-procedural-macros-that-is-not-in-lib-rs/58323/9) - [Quote](https://docs.rs/quote) @@ -1746,18 +1777,12 @@ pub fn foo() -> &'static str { - [Workshop derive builder problem](https://github.com/dtolnay/proc-macro-workshop/blob/master/README.md#derive-macro-derivebuilder) - [Solution hints for builder problem](https://github.com/dtolnay/proc-macro-workshop/blob/master/builder/tests/01-parse.rs) -## Wrapping up +- Source code examples + 1. You can find "real world" examples of both declarative and procedural macros in the + `r3bl-open-core` [repo](https://github.com/r3bl-org/r3bl-open-core). + - [proc macros](https://github.com/r3bl-org/r3bl-open-core/tree/main/macro) + - [decl macros](https://github.com/r3bl-org/r3bl-open-core/search?q=macro_rules) + 2. You can find all the pedagogical examples of macros shown in this article in this + [repo](https://github.com/nazmulidris/rust_scratch/blob/main/macros/). -> πŸ“œ **Source code examples** -> -> 1. You can find "real world" examples of both declarative and procedural macros in the -> `r3bl_rs_utils` [crate](https://crates.io/crates/r3bl_rs_utils). -> -> - [proc macros](https://github.com/r3bl-org/r3bl-open-core/tree/main/macro) -> - [decl macros](https://github.com/r3bl-org/r3bl-open-core/search?q=macro_rules) -> -> 2. You can find all the pedagogical examples of macros shown in this article in this -> [repo](https://github.com/nazmulidris/rust_scratch/blob/main/macros/) -> -> 🌟 Please star the [`r3bl-open-core` repo](https://github.com/r3bl-org/r3bl-open-core) on github if -> you like it πŸ™. +{%- include featured.html -%} diff --git a/_posts/2022-08-04-rust-dsl-part-1.md b/_posts/2022-08-04-rust-dsl-part-1.md index 5eab1c24..5243c230 100644 --- a/_posts/2022-08-04-rust-dsl-part-1.md +++ b/_posts/2022-08-04-rust-dsl-part-1.md @@ -20,6 +20,7 @@ categories: - [Create a DSL for CSS like syntax for TUIs](#create-a-dsl-for-css-like-syntax-for-tuis) + - [A TUI brings GUI features to terminal apps](#a-tui-brings-gui-features-to-terminal-apps) - [What is a style, and how is it used?](#what-is-a-style-and-how-is-it-used) - [Life of a style](#life-of-a-style) - [Going from imperative to declarative style declaration](#going-from-imperative-to-declarative-style-declaration) @@ -35,7 +36,6 @@ categories: ## Create a DSL for CSS like syntax for TUIs - In this article, we will create a simple DSL ([domain specific language](https://docs.microsoft.com/en-us/visualstudio/modeling/about-domain-specific-languages?view=vs-2022)) for CSS like syntax to declaratively create styling for TUI apps. You might be thinking, but why? πŸ€” @@ -45,24 +45,32 @@ The motivation for doing this comes from having built a TUI library in the ergonomic for developers, so that it is easier to use and familiar to declarative styling from CSS, etc. -> 🌟 Please star the [`r3bl-open-core` repo](https://github.com/r3bl-org/r3bl-open-core) on github if -> you like it πŸ™. +{%- include featured.html -%} -> 🦜 What is a TUI? The best way to grok it is to see one in action. -> -> 1. Clone [this repo](https://github.com/r3bl-org/r3bl-cmdr) (for the -> [`r3bl-cmdr` crate](https://crates.io/crates/r3bl-cmdr)) to your local or remote machine. -> - 🌟 Please star [this repo](https://github.com/r3bl-org/r3bl-cmdr) on github if you like it -> πŸ™. -> 2. Run `cargo run` (in `r3bl-cmdr` folder) to see it doing its thing. Works great over -> [SSH](https://en.wikipedia.org/wiki/Secure_Shell) too! -> 3. Check out the source code in this repo, to get a handle on how to use the `r3bl_rs_utils::tui` -> module. - -This TUI library allows developers to build "rich" text user interface apps in Rust, which are fully -async, and leverages ideas from CSS, React, and Redux. Once we built the library, we wanted to make -it easier for developer to declaratively create styling and even layouts, rather than having to do -it imperatively. +### A TUI brings GUI features to terminal apps + + +The best way to grok what a TUI is, is to see one in action. + + + +1. TUI library crate: Clone [this TUI library + repo](https://github.com/r3bl-org/r3bl-open-core/) for the [`r3bl_tui` + crate](https://crates.io/crates/r3bl_tui) to your local or remote machine. You can run + the examples in the + [README](https://github.com/r3bl-org/r3bl-open-core/tree/main/tui#examples-to-get-you-started). +2. TUI apps crate: Clone [this TUI apps + repo](https://github.com/r3bl-org/r3bl-open-core) for the [`r3bl-cmdr` + crate](https://crates.io/crates/r3bl-cmdr) to your local or remote machine. Run `cargo + run` (in `r3bl-cmdr` folder) to see it doing its thing. Works great over + [SSH](https://en.wikipedia.org/wiki/Secure_Shell) too! Or you can just run `cargo + install r3bl-cmdr`. And then run `edi` or `giti`. + +The TUI library allows developers to build "rich" text user interface apps in Rust, which +are fully async, and loosely leverages architectural ideas from CSS, React, web app +development paradigm, and Elm. Once we built the library, we wanted to make it easier for +developer to declaratively create styling and even layouts, rather than having to do it +imperatively. > πŸ’­ In frontend web development, we take it for granted that we can describe things > [declaratively rather than imperatively](https://www.educative.io/blog/declarative-vs-imperative-programming). @@ -678,11 +686,4 @@ In the future we will expand this DSL to include more features like generating t declaratively. And then move on to creating JSX like syntax in Rust for layout stuff in the `tui` module as well. More articles to follow based on this work. -> πŸ“œ For more examples of procedural macros, check out the -> [`r3bl_rs_utils_macro`](https://github.com/r3bl-org/r3bl-open-core/tree/main/macro/) -> repo. -> -> πŸ’‘ This is part of the [`r3bl_rs_utils` crate](https://crates.io/crates/r3bl_rs_utils). -> -> 🌟 Please star the [`r3bl-open-core` repo](https://github.com/r3bl-org/r3bl-open-core) on github if -> you like it πŸ™. +{%- include featured.html -%} diff --git a/_posts/2022-11-21-algo-ts-1.md b/_posts/2022-11-21-algo-ts-1.md index fede5b8a..39010144 100644 --- a/_posts/2022-11-21-algo-ts-1.md +++ b/_posts/2022-11-21-algo-ts-1.md @@ -47,6 +47,8 @@ This tutorial has 2 examples in it: 1. [String tokenizer](#exercise-1-string-tokenizer) 2. [Rate limiter](#exercise-2-in-memory-rate-limiter) +{%- include featured.html -%} + ### How to run this project You can get the code for this and all the other tutorials in this collection from @@ -114,7 +116,7 @@ string. - The meaning of `action` string command: For example `action` can look like this: `"../anotherFolder"`. This means we want to go up one folder (..) and then go into folder - called anotherFolder. + called anotherFolder. In order for us to understand what this `action` string means, we need to break it down into smaller strings and store those smaller strings in an array as well. - For example, `"../anotherFolder"` would be turned into an array of `["..", "anotherFolder"]`. @@ -251,3 +253,5 @@ period. 3. In the outer function we check if the request was successful or not. It the request was successful, we push the request timestamp to `successfulRequests` array and return "accept". If the request was not successful, we return "deny". + +{%- include featured.html -%} diff --git a/_posts/2022-12-11-algo-ts-2.md b/_posts/2022-12-11-algo-ts-2.md index 43ea0d2d..87d7508d 100644 --- a/_posts/2022-12-11-algo-ts-2.md +++ b/_posts/2022-12-11-algo-ts-2.md @@ -44,6 +44,8 @@ created using TypeScript. Information is depicted visually using diagrams and co article may be useful if you are trying to get more fluency in TypeScript or need a refresher to do interview prep for software engineering roles. +{%- include featured.html -%} + ## Pretty print and traverse an HTML tree @@ -269,3 +271,5 @@ All DFS methods use stack data structure. In JavaScript stack is an array where after another and then remove them from the end of the array. It's called last-in-first-out (LIFO). You could think of it as a stack of papers. The last paper you put on the stack is the first paper you take off the stack. + +{%- include featured.html -%} diff --git a/_posts/2023-02-20-guide-to-nom-parsing.md b/_posts/2023-02-20-guide-to-nom-parsing.md index eeb597dc..f6b7f4e9 100644 --- a/_posts/2023-02-20-guide-to-nom-parsing.md +++ b/_posts/2023-02-20-guide-to-nom-parsing.md @@ -28,7 +28,6 @@ categories: ## Introduction - This tutorial is a guide to parsing with nom. It covers the basics of parsing and how to use nom to parse a string into a data structure. We will cover a variety of different examples ranging from parsing simple CSS like syntax to a full blown Markdown parser. @@ -38,6 +37,8 @@ This tutorial has 2 examples in it: 1. [CSS style syntax](#getting-to-know-nom-using-a-simple-example) 2. [Markdown parser](#build-a-markdown-parser) +{%- include featured.html -%} + > For more information on general Rust type system design (functional approach rather than > object oriented), please take a look at this [paper](https://arxiv.org/pdf/2307.07069.pdf) > by Will Crichton demonstrating Typed Design Patterns with Rust. @@ -45,7 +46,6 @@ This tutorial has 2 examples in it: ## Documentation - nom is a huge topic. This tutorial takes a hands on approach to learning nom. However, the resources listed below are very useful for learning nom. Think of them as a reference guide and deep dive into how the nom library works. @@ -314,7 +314,6 @@ complex parsers. You start w/ the simplest one first, and then build up from the ## Build a Markdown parser - > πŸ’‘ You can get the source code for the Markdown parser shown in this article from the > [`r3bl-open-core`](https://github.com/r3bl-org/r3bl-open-core/tree/main/tui/src/tui/md_parser) > repo. @@ -351,3 +350,5 @@ Here are some entry points into the codebase. that are used to represent the Markdown document model ([`Document`](https://github.com/r3bl-org/r3bl-open-core/blob/main/tui/src/tui/md_parser/types.rs)) and all the other intermediate types (`Fragment`, `Block`, etc) & enums required for parsing. + +{%- include featured.html -%} diff --git a/_posts/2023-08-28-justfile.md b/_posts/2023-08-28-justfile.md index e81390fd..526f9e34 100644 --- a/_posts/2023-08-28-justfile.md +++ b/_posts/2023-08-28-justfile.md @@ -38,15 +38,7 @@ with `cargo`. Before we get started, please take a look at the [`just` project README](https://github.com/casey/just). -> πŸš€ Please star and fork / clone the [r3bl_ansi_color -> repo](https://github.com/r3bl-org/r3bl-open-core/tree/main/ansi_color) 🌟. We will use -> this repo as an example to learn how to use `just` to manage project specific commands. -> -> If you would like to get involved in an open source project and like Rust crates, please -> feel free to contribute to the [r3bl_ansi_color -> repo](https://github.com/r3bl-org/r3bl-open-core/contribute). There are a lot of small -> features that need to be added. And they can be a nice stepping stone into the world of -> open source contribution πŸŽ‰. +{%- include featured.html -%} Let's say you have a `justfile` that looks like this, and it has a single recipe called `list`: @@ -258,12 +250,4 @@ some interesting links inside the README: 1. [Conditional expressions](https://github.com/casey/just#conditional-expressions). 1. [Setting variables](https://github.com/casey/just#setting-variables-from-the-command-line). -> πŸš€ Please star and fork / clone the [r3bl_ansi_color -> repo](https://github.com/r3bl-org/r3bl-open-core/tree/main/ansi_color) 🌟. We will use -> this repo as an example to learn how to use `just` to manage project specific commands. -> -> If you would like to get involved in an open source project and like Rust crates, please -> feel free to contribute to the [r3bl_ansi_color -> repo](https://github.com/r3bl-org/r3bl-open-core/contribute). There are a lot of small -> features that need to be added. And they can be a nice stepping stone into the world of -> open source contribution πŸŽ‰. +{%- include featured.html -%} diff --git a/_posts/2023-09-17-tuify-clap.md b/_posts/2023-09-17-tuify-clap.md index ddbf8f19..781bf7df 100644 --- a/_posts/2023-09-17-tuify-clap.md +++ b/_posts/2023-09-17-tuify-clap.md @@ -48,14 +48,7 @@ CLI apps to make them more ergonomic to use. And we can do this without going fu this in a way that is additive to the existing CLI experience. We can "tuify" our CLI apps that are built using `clap`. -> πŸš€ Please star and fork / clone the -> [r3bl_tuify repo](https://github.com/r3bl-org/r3bl-open-core/tree/main/tuify) 🌟. We will use this -> repo as an example to learn how to add minimal interactivity to your clap CLI apps -> -> If you would like to get involved in an open source project and like Rust crates, please feel free -> to contribute to the [r3bl_tuify repo](https://github.com/r3bl-org/r3bl-open-core/contribute). -> There are a lot of small features that need to be added. And they can be a nice stepping stone -> into the world of open source contribution πŸŽ‰. +{%- include featured.html -%} > For more information on general Rust type system design (functional approach rather than > object oriented), please take a look at this [paper](https://arxiv.org/pdf/2307.07069.pdf) @@ -325,11 +318,4 @@ existing CLI experiences. Things like multi line editor component w/ syntax high scroll view, form input fields, and more. If you would like to contribute to this effort, it would be great to have your help. -> πŸš€ Please star and fork / clone the -> [r3bl_tuify repo](https://github.com/r3bl-org/r3bl-open-core/tree/main/tuify) 🌟. We will use this -> repo as an example to learn how to add minimal interactivity to your clap CLI apps -> -> If you would like to get involved in an open source project and like Rust crates, please feel free -> to contribute to the [r3bl_tuify repo](https://github.com/r3bl-org/r3bl-open-core/contribute). -> There are a lot of small features that need to be added. And they can be a nice stepping stone -> into the world of open source contribution πŸŽ‰. +{%- include featured.html -%} diff --git a/_posts/2023-09-22-overcome-your-fear-of-merge-conflicts.md b/_posts/2023-09-22-overcome-your-fear-of-merge-conflicts.md index e78bfc12..184dfb90 100644 --- a/_posts/2023-09-22-overcome-your-fear-of-merge-conflicts.md +++ b/_posts/2023-09-22-overcome-your-fear-of-merge-conflicts.md @@ -27,7 +27,6 @@ categories: ## Introduction - There are few things that generate as much fear and anxiety in developers as `git` merge conflicts. `git` is very popular and very powerful, and it is a low level command line tool. And it is not very user friendly. It is meant to be orchestrate-able and automated @@ -41,6 +40,8 @@ TUIs, or even conversational interfaces. But that's not the focus of this article which is all about the CLI experience of inducing and resolving merge conflicts. So let's get started. +{%- include featured.html -%} + ## Setting the stage for a merge conflict @@ -141,11 +142,5 @@ Let's use some pictures to understand the story of how we got here. And how to r ## Next steps -> If you would like to get involved in an open source project and like Rust crates, please -> consider contributing to the [r3bl_tuify -> repo](https://github.com/r3bl-org/r3bl-open-core/contribute). There are a lot of small -> features that need to be added. And they can be a nice stepping stone into the world of -> open source contribution πŸŽ‰. -> -> πŸš€ Please star and fork / clone the -> [r3bl_tuify repo](https://github.com/r3bl-org/r3bl-open-core/tree/main/tuify) 🌟. + +{%- include featured.html -%} diff --git a/_posts/2024-01-13-write-simple-char-server-in-rust.md b/_posts/2024-01-13-write-simple-char-server-in-rust.md new file mode 100644 index 00000000..089b1cbd --- /dev/null +++ b/_posts/2024-01-13-write-simple-char-server-in-rust.md @@ -0,0 +1,393 @@ +--- +title: "Write a simple TCP chat server in Rust" +author: Nazmul Idris +date: 2024-01-13 15:00:00+00:00 +excerpt: | + A guide on how to create write a simple TCP chat server in Rust + using Tokio +layout: post +categories: + - Rust + - CLI + - Server +--- + + + + + +- [Build a chat server using Tokio](#build-a-chat-server-using-tokio) +- [The chat server comprises all these pieces](#the-chat-server-comprises-all-these-pieces) +- [Add dependencies to Cargo.toml](#add-dependencies-to-cargotoml) +- [Main function](#main-function) + - [tokio::spawn does not spawn a new thread, so what does it actually do?](#tokiospawn-does-not-spawn-a-new-thread-so-what-does-it-actually-do) +- [Handle client task function](#handle-client-task-function) + - [Two concurrent tasks in the tokio::select! block](#two-concurrent-tasks-in-the-tokioselect-block) + - [Handle read from broadcast channel function](#handle-read-from-broadcast-channel-function) + - [Handle socket read function](#handle-socket-read-function) +- [Next steps](#next-steps) + + + +## Build a chat server using Tokio + + +In this tutorial we will build a simple chat server using Tokio. The server will be able +to handle multiple clients, and each client will be able to send messages to the server, +which will then broadcast the message to all other connected clients. + +- We will use Tokio's `tokio::net::TcpListener` and `tokio::net::TcpStream` to create a + TCP server that listens for incoming connections and handles them concurrently. +- We will also use Tokio's `tokio::sync::broadcast` to broadcast messages to all connected + clients. + +Read [this tutorial]({{ '/2024/01/13/write-simple-netcat-in-rust/' | relative_url}}) to +learn more about the basics of TCP client and server programming in Rust (without using +Tokio). + +{%- include featured.html -%} + +Here's a video of the app that we will build in action. + + + +> You can find the finished source code for this tutorial +> [here](https://github.com/nazmulidris/rust-scratch/tree/main/tcp-server-netcat-client). + + +## The chat server comprises all these pieces + + +```text + β”Œβ”€CLIENT-1───────┐ β”Œβ”€CLIENT─2───────┐ β”Œβ”€CLIENT─3──────┐ + β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ β”‚ β”‚ +β”Œβ”€SERVER───┼──────────────────────┼────────────────────────┼────────────┐ +β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ +β”‚ handle_client_task() handle_client_task() handle_client_task() β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ β”Œβ”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β” β”‚ β”‚ β”Œβ”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β” β”‚ β”‚ β”Œβ”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β” β”‚ β”‚ +β”‚ β”‚ β”‚ TX β”‚ β”‚ RX β”‚ β”‚ β”‚ β”‚ TX β”‚ β”‚ RX β”‚ β”‚ β”‚ β”‚ TX β”‚ β”‚ RX β”‚ β”‚ β”‚ +β”‚ β”‚ β””β”€β”¬β”€β”€β”˜ β””β”€β–²β”€β”€β”˜ β”‚ β”‚ β””β”€β”¬β”€β”€β”˜ β””β”€β–²β”€β”€β”˜ β”‚ β”‚ β””β”€β”¬β”€β”€β”˜ β””β”€β–²β”€β”€β”˜ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ (TX, RX) = channel::broadcast() β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + + + +The server has a `main` function that creates a `tokio::net::TcpListener` and listens for +incoming connections. When a new connection is received, it spawns a new task to handle +the connection using `tokio::spawn()`. + +Using `tokio::select!`, the task tries to do the following concurrently, and waits until +one of them completes: +1. The task reads messages from its client and broadcasts them to all other connected + clients. It also echoes the message back to its client. +2. The task listens for messages from other clients and sends them to its client. + +When one task above completes, the other is dropped. Then the code path with the completed +task executes. Then the code returns to the infinite loop, if it hasn't returned already. + +A client can be any TCP client, such as `telnet`, `nc`, or PuTTY. + +## Add dependencies to Cargo.toml + + +Let's create a new project by running `cargo create --bin tcp-server-netcat-client`. Then +we will add the following dependencies to our `Cargo.toml` file. + +```toml +# tokio. +tokio = { version = "1.35.1", features = ["full"] } + +# stdout logging. +femme = { version = "2.2.1" } +log = { version = "0.4.20" } + +# r3bl_rs_utils_core - friendly name generator. +r3bl_rs_utils_core = { version = "0.9.12" } +r3bl_tui = { version = "0.5.1" } +``` + +## Main function + + +We will implement the following algorithm for our server in our main function: +1. Create a broadcast channel. It will be shared by all the client tasks. +2. Create `TcpListener` and bind to an address & port. +3. Loop: + - Accept socket connection, and get its `TCPStream`. + - Use `tokio::spawn()` to spawn a task to handle this client connection and its + `TCPStream`. + +In the task that handles the connection: +1. Get `BufReader` & `BufWriter` from the `TCPStream`. The reader and writer allow us to + read data from and write data to the client socket. +2. Loop: + - Use `tokio::select!` to concurrently: + - Read from broadcast channel (via `recv()`): + - Send the message to the client (only if it is from a different client) over the + socket (use `BufWriter` to write the message). + - Read from socket (via `BufReader::read_line()`): + - Read `incoming` from reader. + - Call `process(incoming)` and generate `outgoing`. This colorizes the `incoming` + message with a lolcat effect to generate the `outgoing` message. + - Send `incoming` message to other connected clients (via the broadcast channel). + +> You can find the finished source code for this tutorial +> [here](https://github.com/nazmulidris/rust-scratch/tree/main/tcp-server-netcat-client). + +Here's the code for the main function, and some supporting type aliases and structs: + +```rust +pub type IOResult = std::io::Result; + +#[derive(Debug, Clone)] +pub struct MsgType { + pub socket_addr: SocketAddr, + pub payload: String, + pub from_id: String, +} + +#[tokio::main] +pub async fn main() -> IOResult<()> { + let addr = "127.0.0.1:3000"; + + // Start logging. + femme::start(); + + // Create TCP listener. + let tcp_listener = TcpListener::bind(addr).await?; + log::info!("Server is ready to accept connections on {}", addr); + + // Create channel shared among all clients that connect to the server loop. + let (tx, _) = broadcast::channel::(10); + + // Server loop. + loop { + // Accept incoming socket connections. + let (tcp_stream, socket_addr) = tcp_listener.accept().await?; + + let tx = tx.clone(); + tokio::spawn(async move { + let result = handle_client_task(tcp_stream, tx, socket_addr).await; + match result { + Ok(_) => { + log::info!("handle_client_task() terminated gracefully") + } + Err(error) => log::error!("handle_client_task() encountered error: {}", error), + } + }); + } +} +``` + +To run the server, you can run `cargo run`. There are no command line arguments to pass or +parse. + +### tokio::spawn does not spawn a new thread, so what does it actually do? + + +Since `tokio::spawn` sounds similar to `thread::spawn` it might be easy to assume that +`tokio::spawn` creates a new thread. This would go against the idea of even using tokio +(which is all about concurrency and non blocking IO), since handling one connection per +thread isn't [scalable](https://g.co/bard/share/74f433bad400), which is what we did in +this tutorial: [Write a simple TCP chat server in Rust]({{ +'/2024/01/13/write-simple-netcat-in-rust/' | relative_url}}). + +`tokio::spawn` does not create a thread; it creates a Tokio task, which is a +co-operatively scheduled entity that Tokio knows how to schedule on the Tokio runtime (in +turn, the Tokio runtime can have as many worker threads as you want - from 1 upwards). + +By using `tokio::spawn`, you allow the Tokio runtime to switch to another task at points +in the task where it has a `.await`, and only those points. Your alternative, if you don't +want multiple tasks, is to use things like `select!`, `join!` and functions with `select` +or ` join` in their name to have concurrent I/O in a single task. + +The point of spawning in Tokio is twofold: + +1. If your runtime has multiple threads, then two tasks can execute in parallel on + different threads, reducing latency. +2. It is almost always easier to understand a complex program in terms of different tasks + doing their work, than in terms of a single large task doing lots of work concurrently + (e.g. using `select` to wait for one of many options, or `join` to wait for all options + to finish). + +> You can get more info on this topic +> [here](https://users.rust-lang.org/t/socket-per-thread-in-tokio/83712/7). + +## Handle client task function + + +The `handle_client_task` function is where all the magic happens. +1. It reads messages from its client (over TCP socket) and broadcasts them to all other + connected clients. +2. It processes the message from its client and echoes it back to its client (over TCP + socket). +3. It reads messages from other clients (over broadcast channel) and sends them to its + client (over socket). + +Here's the code for the `handle_client_task()` function: + +```rust +async fn handle_client_task( + mut tcp_stream: TcpStream, + tx: Sender, + socket_addr: SocketAddr, +) -> IOResult<()> { + log::info!("Handle socket connection from client"); + + let id = friendly_random_id::generate_friendly_random_id(); + let mut rx = tx.subscribe(); + + // Set up buf reader and writer. + let (reader, writer) = tcp_stream.split(); + let mut reader = BufReader::new(reader); + let mut writer = BufWriter::new(writer); + + // Send welcome message to client w/ ids. + let welcome_msg_for_client = + ColorWheel::lolcat_into_string(&format!("addr: {}, id: {}\n", socket_addr, id)); + writer.write(welcome_msg_for_client.as_bytes()).await?; + writer.flush().await?; + + let mut incoming = String::new(); + + loop { + let tx = tx.clone(); + tokio::select! { + // Read from broadcast channel. + result = rx.recv() => { + read_from_broadcast_channel(result, socket_addr, &mut writer, &id).await?; + } + + // Read from socket. + network_read_result = reader.read_line(&mut incoming) => { + let num_bytes_read: usize = network_read_result?; + // EOF check. + if num_bytes_read == 0 { + break; + } + handle_socket_read(num_bytes_read, &id, &incoming, &mut writer, tx, socket_addr).await?; + incoming.clear(); + } + } + } + + Ok(()) +} +``` + +### Two concurrent tasks in the tokio::select! block + + +1. Read from broadcast channel. The function `read_from_broadcast_channel()` does this work. +2. Read from socket. The function `handle_socket_read()` does this work. + +Whichever task completes first, the `tokio::select!` block will go down that code path, +and drop the other task. + +### Handle read from broadcast channel function + + +Here's the code for the `read_from_broadcast_channel()` function: + +```rust +async fn read_from_broadcast_channel( + result: Result, + socket_addr: SocketAddr, + writer: &mut BufWriter>, + id: &str, +) -> IOResult<()> { + match result { + Ok(it) => { + let msg: MsgType = it; + log::info!("[{}]: channel: {:?}", id, msg); + if msg.socket_addr != socket_addr { + writer.write(msg.payload.as_bytes()).await?; + writer.flush().await?; + } + } + Err(error) => { + log::error!("{:?}", error); + } + } + + Ok(()) +} +``` + +### Handle socket read function + + +Here's the code for the `handle_socket_read()` function: + +```rust +async fn handle_socket_read( + num_bytes_read: usize, + id: &str, + incoming: &str, + writer: &mut BufWriter>, + tx: Sender, + socket_addr: SocketAddr, +) -> IOResult<()> { + log::info!( + "[{}]: incoming: {}, size: {}", + id, + incoming.trim(), + num_bytes_read + ); + + // Process incoming -> outgoing. + let outgoing = process(&incoming); + + // outgoing -> Writer. + writer.write(outgoing.as_bytes()).await?; + writer.flush().await?; + + // Broadcast outgoing to the channel. + let _ = tx.send(MsgType { + socket_addr, + payload: incoming.to_string(), + from_id: id.to_string(), + }); + + log::info!( + "[{}]: outgoing: {}, size: {}", + id, + outgoing.trim(), + num_bytes_read + ); + + Ok(()) +} + +fn process(incoming: &str) -> String { + // Remove new line from incoming. + let incoming_trimmed = format!("{}", incoming.trim()); + // Colorize it. + let outgoing = ColorWheel::lolcat_into_string(&incoming_trimmed); + // Add new line back to outgoing. + format!("{}\n", outgoing) +} +``` + +## Next steps + + +{%- include featured.html -%} diff --git a/_posts/2024-01-13-write-simple-netcat-in-rust.md b/_posts/2024-01-13-write-simple-netcat-in-rust.md new file mode 100644 index 00000000..55d55f6b --- /dev/null +++ b/_posts/2024-01-13-write-simple-netcat-in-rust.md @@ -0,0 +1,468 @@ +--- +title: "Write a simple netcat client and server in Rust" +author: Nazmul Idris +date: 2024-01-13 15:00:00+00:00 +excerpt: | + A guide on how to a simple Rust netcat client and server +layout: post +categories: + - Rust + - CLI + - Server +--- + + + + + +- [Build a Swiss Army knife for networking](#build-a-swiss-army-knife-for-networking) +- [Add dependencies to Cargo.toml](#add-dependencies-to-cargotoml) +- [Configure clap to parse command line arguments](#configure-clap-to-parse-command-line-arguments) +- [Create the client](#create-the-client) +- [Create the server](#create-the-server) +- [Next steps](#next-steps) + + + +## Build a Swiss Army knife for networking + + +In this tutorial we will learn how to use Rust to write a simple netcat client and server +using the standard library only. A netcat client is like a Swiss Army knife for +networking. It is similar to PuTTY and telnet. You can use it to connect to a server and +send and receive data. We will create an app that can behave both as a client and server. + +1. Our client will allow the user to type a message and send it to any TCP socket server, + and display the response from the server, in an endless loop. +2. Our server will listen for incoming TCP connections from clients, and display the + message from the client, and send a response back to the client. + +{%- include featured.html -%} + +Here's a video of the app that we will build in action. + + + +> You can find the finished source code for this tutorial +> [here](https://github.com/nazmulidris/rust-scratch/tree/main/rtelnet). + +## Add dependencies to Cargo.toml + + +Let's create a new project by running `cargo create --bin rtelnet`. Then we will add the +following dependencies to our `Cargo.toml` file. + +```toml +# Command line argument parsing. +clap = { version = "4.4.13", features = ["derive"] } + +# Pretty logging. +femme = { version = "2.2.1" } +log = { version = "0.4.20" } + +# Colorization and ANSI escape sequence codes. +r3bl_tui = { version = "0.5.1" } +r3bl_ansi_color = { version = "0.6.9" } +``` + +## Configure clap to parse command line arguments + + +This Rust app has a single binary, and depending on the command line arguments, it will behave +either as a client or server. We will use the `clap` crate to parse the command line arguments. + +We will configure `clap` so that the following commands will work: + +```bash +cargo run server +cargo run client +``` + +We want to allow the user to specify the following options and chose their own address and +port. If the user does not specify any options, we will use the default values. The +default value for `--address` is `127.0.0.1`, and the default value for `--port` is +`3000`. + +```bash +cargo run server --address 127.0.0.1 --port 8080 +cargo run server --address 127.0.0.1 +cargo run server --port 8080 + +cargo run client --address 127.0.0.1 --port 8080 +cargo run client --address 127.0.0.1 +cargo run client --port 8080 +``` + +Let's also add an option that we can use to disable log output to stdout. By default, we +will log to stdout. But if the user specifies the `--log-disable` flag, then we disable +all log output. + +Here's the clap configuration that gives us this behavior. + +```rust +use clap::{Parser, Subcommand}; + +pub use defaults::*; +mod defaults { + use super::*; + + pub const DEFAULT_PORT: u16 = 3000; + pub const DEFAULT_ADDRESS: &str = "127.0.0.1"; +} + +pub use clap_config::*; +mod clap_config { + use super::*; + + #[derive(Parser, Debug)] + pub struct CLIArg { + /// IP Address to connect to or start a server on + #[clap(long, short, default_value = DEFAULT_ADDRESS, global = true)] + pub address: IpAddr, + + /// TCP Port to connect to or start a server on + #[clap(long, short, default_value_t = DEFAULT_PORT, global = true)] + pub port: u16, + + /// Logs to stdout by default, set this flag to disable it + #[clap(long, short = 'd', global = true)] + pub log_disable: bool, + + /// The subcommand to run + #[clap(subcommand)] + pub subcommand: CLISubcommand, + } + + #[derive(Subcommand, Debug)] + pub enum CLISubcommand { + /// Start a server on the given address and port + Server, + /// Connect to a server running on the given address and port + Client, + } +} +``` + +## Create the client + + +Let's start with the simpler of the two, the client. We will use `std::net::TcpStream` to +create a TCP socket client. We will need an IP address and port in order to make a TCP +connection. And to run the client we will need to run the following command: + +```bash +cargo run client +``` + +Here's what the main function of our app looks like: + +```rust +fn main() { + println!("Welcome to rtelnet"); + + let cli_arg = CLIArg::parse(); + let address = cli_arg.address; + let port = cli_arg.port; + let socket_address = format!("{}:{}", address, port); + + if !cli_arg.log_disable { + femme::start() + } + + match match cli_arg.subcommand { + CLISubcommand::Server => start_server(socket_address), + CLISubcommand::Client => start_client(socket_address), + } { + Ok(_) => { + println!("Program exited successfully"); + } + Err(error) => { + println!("Program exited with an error: {}", error); + } + } +} +``` + +The function that performs the client logic looks like this. + +```rust +fn start_client(socket_address: String) -> IOResult<()> { + log::info!("Start client connection"); + let tcp_stream = TcpStream::connect(socket_address)?; + let (mut reader, mut writer) = (BufReader::new(&tcp_stream), BufWriter::new(&tcp_stream)); + + // Client loop. + loop { + // Read user input. + let outgoing = { + let mut it = String::new(); + let _ = stdin().read_line(&mut it)?; + it.as_bytes().to_vec() + }; + + // Tx user input to writer. + let _ = writer.write(&outgoing)?; + writer.flush()?; + + // Rx response from reader. + let incoming = { + let mut it = vec![]; + let _ = reader.read_until(b'\n', &mut it); + it + }; + + let display_msg = String::from_utf8_lossy(&incoming); + let display_msg = display_msg.trim(); + + let reset = SgrCode::Reset.to_string(); + let display_msg = format!("{}{}", display_msg, reset); + println!("{}", display_msg); + + // Print debug. + log::info!( + "-> Tx: '{}', size: {} bytes{}", + String::from_utf8_lossy(&outgoing).trim(), + outgoing.len(), + reset, + ); + log::info!( + "<- Rx: '{}', size: {} bytes{}", + String::from_utf8_lossy(&incoming).trim(), + incoming.len(), + reset, + ); + } +} +``` + +Here are a few things to note about the client code: +- We create a `BufReader` and `BufWriter` for the `TcpStream` that we get from + `TcpStream::connect()`. This is because we want to read and write data in chunks, and + not one byte at a time, for performance reasons, and to simplify the logic. These two + structs allow us to read and write data very easily in chunks that are delimited by new + lines (`\n`). +- There's a client loop that runs forever. This is because we want to keep the client + running forever, so that the user can type a message and send it to the server, and + receive a response from the server. +- How do we exit this infinite client loop? Only when the user presses `Ctrl+C` will the + client exit. The [default behavior](https://g.co/bard/share/ac5d3480eb37) for Rust is to + exit the process when this happens. This drops the TCP connection causing the server to exit as + well. +- When we read data from user input, it too uses a stream, not a `TcpStream`, but the + `stdin()` stream. This behaves very similarly to the `TcpStream` stream. We can read + data from it in chunks delimited by new lines (`\n`). Once the user types a message and + presses enter that message, eg: `"hi"`, and the new line are stored in the `it` + variable, eg: `"hi\n"`. We then convert the String into a byte array, eg: `[104, 105, + 10]`, and then convert it into a `Vec`. We then send it to the server. We must call + `flush()` since `BufWriter` buffers the data and does not send it to the server until we + call `flush()` for IO performance reasons. It queue's up the data and sends it in + chunks, instead of sending it one byte at a time. +- Reading there response from the server is similar to reading it from `stdin()` as we + have already seen. The main thread blocks until there is some data that can be read from + the server. Or if the TCP connection errors out in any way (timeout or closed by various + means). If there is an error, then this function returns an error, and the main thread + exits. Note that the `start_client()` function itself returns an `IOResult`, which is + just a type alias for `pub type IOResult = std::io::Result;`. The error handling + is quite simple. If there is an error, we print it out and exit the program. +- We read the data from the server into the `incoming` variable using + `reader.read_until(b'\n', &mut it);)`. This is because we expect the server to send us + data that is terminated by a new line (`\n`). So we read the data until we encounter a + new line. This is a blocking call, so the main thread blocks until there is some data + that can be read from the server. Note that the `\n` is included in `incoming` variable, + much like it is in `stdin()`. + - We use this function `String::from_utf8_lossy(&incoming);` to convert this `incoming: + Vec` into a `String`. We call `.trim()` on the String, so that the trailing `\n` + is removed. + - Note that `trim()` returns a `&str`, so if you want to turn it into a String, you have + to run in through this expression `format!("{}", + String::from_utf8_lossy(&incoming).trim())` function. +- This is a pedagogical example and this algorithm is somewhat contrived to demonstrate + how to send bytes back and forth between client and server and have them interpret the + bytes in a certain way. A more formalized version of this "dance" is called a + "protocol", eg: HTTP, SMTP, etc. +- In the final step of the `loop`, after the incoming data has been read from the server, + we print it out to the terminal. Since the server will send us ANSI escape sequence + codes that colorize the text that we print to the terminal, we want to reset the color + after we print the text, so it does not pollute our `stdout()` output stream. We use the + [`SgrCode::Reset` code to reset the + color](https://github.com/r3bl-org/r3bl-open-core/blob/main/ansi_color/src/ansi_escape_codes.rs#L23) + of the text that we print to the terminal. + +## Create the server + + +Now let's create the server. We will use `std::net::TcpListener` to create a TCP socket +server. We will need an IP address and port in order to make a TCP connection. To run the +server we will need to run the following command: + +```bash +cargo run server +``` + +The server code is very similar to the client code. We need a server loop that runs +forever, and we need to first read (blocking until there is any data available) and then +write data in chunks delimited by new lines (`\n`). When there is no data available to +read `EOF` is reached on the reader (aka, input TCP stream) then we break out of this loop +and exit. When data comes in (delimited by `\n`) we process it and send a response back to +the client. We process this data by applying a [lolcat +effect](https://github.com/r3bl-org/r3bl-open-core/blob/main/tui/src/tui/color_wheel/color_wheel_struct.rs#L457) +on it, so the client will get a very colorful version of whatever text message that they +sent to the server. + +One more thing we will see when implementing the server is having to spawn multiple +threads to handle each incoming client connection. While the client is a single threaded +app, the server is a multi-threaded app. The client is only concerned w/ a single TCP +connection, but the server is concerned with multiple TCP connections, each connection +emanating from a different client process running the `cargo run client` and creating a +new OS process. Fortunately Rust is built for fearless concurrency and parallelism from +the ground up. + +Here's the main function of our server app: + +```rust +pub fn start_server(socket_address: String) -> IOResult<()> { + let tcp_listener = TcpListener::bind(socket_address)?; + // Server connection accept loop. + loop { + log::info!("Waiting for a incoming connection..."); + let (tcp_stream, ..) = tcp_listener.accept()?; // This is a blocking call. + + // Spawn a new thread to handle this connection. + thread::spawn(|| match handle_connection(tcp_stream) { + Ok(_) => { + log::info!("Successfully closed connection to client..."); + } + Err(_) => { + log::error!("Problem with client connection..."); + } + }); + } +} +``` + +Here are a few things to note about the server code: +- We are using `IOResult` just like the client code. There are frequent calls to the `?` + operator, which is shorthand for matching on the `Result` and returning early if there's + an error. This is rudimentary error handling, and its good enough for this pedagogical + example. Note that even in this pedagogical example, we don't use the `unwrap()` method + which will induce a panic if there's an error. We always use the `?` operator, which + will return early if there's an error. It isn't a good idea to get into the habit of + using `unwrap()` outside of tests. These habits are hard to break once they're formed. + You can even add the following + [`#![warn(clippy::unwrap_in_result)]`](https://rust-lang.github.io/rust-clippy/master/index.html#/unwrap_used) + in the top level module of your project to have the compiler warn you if you use + `unwrap()` outside of tests. Here's an + [example](https://github.com/r3bl-org/r3bl-open-core/blob/main/ansi_color/src/lib.rs#L171). +- The first thing the server has to do is reserve a port on the given address. This is called + binding, and we do it using `TcpListener::bind(socket_address)?;`. This does not start a server + yet. It just reserves a port on the given address, assuming that it is available. If some other + process has already bound to that port, then this will return an error. +- Once we have a `TcpListener` instance, we can call `accept()` on it to start listening + for incoming connections. This is a blocking call, so the main thread blocks until there + is an incoming connection. Once there is an incoming connection, we get a `TcpStream` + instance, which we can use to read and write data to the client. This is a blocking + call. Which means that the main thread won't be able to do anything else, like process + other incoming connections, while it is waiting here, for a connection to come in. +- This is why we use `thread::spawn()` to create a new thread and have it handle the + incoming connection. We spawn a new thread for each incoming connection. This is [not a + scalable solution](https://g.co/bard/share/74f433bad400), but it is good enough for this + pedagogical example. We will learn about more scalable solutions in a the [Write a + simple TCP chat server in Rust]({{ '/2024/01/13/write-simple-char-server-in-rust/' | + relative_url}}) tutorial. + +Now, let's look at the `handle_connection()` function that is called by the spawned +thread. This is the function that handles the incoming connection from the client. And it +defines our "protocol", along with the client code. We aren't using any formalized +protocol like HTTP or SMTP. We are just sending bytes back and forth between the client +and server, and interpreting them in a certain way, which is our informal protocol. This +code is very similar to the client side code, including the `loop` and the `BufReader` and +`BufWriter` structs. And even looking for `EOF` to break out of the loop. Except that we +don't block on `stdin()` for input here. + +```rust +fn handle_connection(tcp_stream: TcpStream) -> IOResult<()> { + log::info!("Start handle connection"); + + let reader = &mut BufReader::new(&tcp_stream); + let write = &mut BufWriter::new(&tcp_stream); + + // Process client connection loop. + loop { + let mut incoming: Vec = vec![]; + + // Read from reader. + let num_bytes_read = reader.read_until(b'\n', &mut incoming)?; + + // Check for EOF. The stream is closed. + if num_bytes_read == 0 { + break; + } + + // Process. + let outgoing = process(&incoming); + + // Write to writer. + write.write(&outgoing)?; + let _ = write.flush()?; + + // Print debug. + log::info!("-> Rx(bytes) : {:?}", &incoming); + log::info!( + "-> Rx(string): '{}', size: {} bytes", + String::from_utf8_lossy(&incoming).trim(), + incoming.len(), + ); + log::info!( + "<- Tx(string): '{}', size: {} bytes", + String::from_utf8_lossy(&outgoing).trim(), + outgoing.len() + ); + } + + log::info!("End handle connection - connection closed"); + + Ok(()) +} +``` + +Finally, let's look at the `process()` function that takes the incoming bytes to the +outgoing bytes. This is where we add some fun and color and flair to our app. We colorize +the incoming bytes using a lolcat effect and send it back to the client. + +```rust +use r3bl_tui::ColorWheel; + +fn process(incoming: &Vec) -> Vec { + // Convert incoming to String, and remove any trailing whitespace (includes newline). + let incoming = String::from_utf8_lossy(incoming); + let incoming = incoming.trim(); + + // Prepare outgoing payload. + let outgoing = incoming.to_string(); + + // Colorize it w/ a gradient. + let outgoing = ColorWheel::lolcat_into_string(&outgoing); + + // Generate outgoing response. Add newline to the end of output (so client can process it). + let outgoing = format!("{}\n", outgoing); + + // Return outgoing payload. + outgoing.as_bytes().to_vec() +} +``` + +## Next steps + + +Now that you have a handle on the basics of writing a simple netcat client and server, you +can read [this tutorial]({{ '/2024/01/13/write-simple-char-server-in-rust/' | +relative_url}}) to learn more about creating a more advanced TCP server that netcat, +telnet, or PuTTY clients can connect to, in order to have multiple client apps chat with +each other. + +{%- include featured.html -%} diff --git a/_sass/code-block.scss b/_sass/code-block.scss index 48542cc8..1f7c50e0 100644 --- a/_sass/code-block.scss +++ b/_sass/code-block.scss @@ -53,8 +53,10 @@ pre { // Applies to code blocks, where is nested inside 
    .
 pre {
+  line-height: 1.2;
   overflow-x: auto;
   > code {
+    line-height: 1.2;
     border: 0;
     padding-left: 0;
     padding-right: 0;
diff --git a/_sass/globals.scss b/_sass/globals.scss
index 469a65b6..13138034 100644
--- a/_sass/globals.scss
+++ b/_sass/globals.scss
@@ -34,8 +34,8 @@ $specialHeadingFontFamily: "Gotham Bold", "Monocraft", "Mabry Pro", "Ndot-55";
 
 $headingFontFamily: "Monocraft", "Mabry Pro", "Gotham Bold", "Spline Sans", "Helvetica Neue", "Google Sans", "Work Sans", Arial, sans-serif;
 $baseFontFamily: "Iosevka Term Web", "Victor Mono", "Spline Sans Mono", "Fira Mono", "Fira Sans", "JetBrains Mono", "Helvetica Neue", "Lexend Deca", sans-serif;
-$baseFontSize: 13pt;
-$baseFontWeight: 500;
+$baseFontSize: 12.5pt;
+$baseFontWeight: 400;
 $baseLineHeight: 1.6;
 
 $smallFontSize: $baseFontSize * 0.875;
diff --git a/_sass/minima/_base.scss b/_sass/minima/_base.scss
index 34384842..38972f1b 100644
--- a/_sass/minima/_base.scss
+++ b/_sass/minima/_base.scss
@@ -273,7 +273,7 @@ h3 code {
  * Sidebar
  */
 .sidebar {
-  padding: 0 15px 30px 15px; 
+  padding: 0 15px 30px 15px;
   position: sticky;
   top: 0;
 }
@@ -356,7 +356,7 @@ table {
 
 @media screen and (min-width: 801px) {
   .sidebar {
-    padding: 30px; 
+    padding: 30px;
     max-width: 330px;
   }
 
diff --git a/assets/chatserver-hero.svg b/assets/chatserver-hero.svg
new file mode 100644
index 00000000..bfea3544
--- /dev/null
+++ b/assets/chatserver-hero.svg
@@ -0,0 +1,108 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/assets/chatserver.svg b/assets/chatserver.svg
new file mode 100644
index 00000000..d2fec6a0
--- /dev/null
+++ b/assets/chatserver.svg
@@ -0,0 +1,86 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/assets/netcat-hero.svg b/assets/netcat-hero.svg
new file mode 100644
index 00000000..a56ba70c
--- /dev/null
+++ b/assets/netcat-hero.svg
@@ -0,0 +1,108 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/assets/netcat.svg b/assets/netcat.svg
new file mode 100644
index 00000000..c182e37c
--- /dev/null
+++ b/assets/netcat.svg
@@ -0,0 +1,86 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+