merge branch docs-mkdocs at once

adalkiran · Apr 11, 2024 · d8d5434 · d8d5434
1 parent ebf56bd
commit d8d5434
Show file tree

Hide file tree

Showing 23 changed files with 642 additions and 290 deletions.
diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml
@@ -0,0 +1,3 @@
+# These are supported funding model platforms
+
+github: [adalkiran]
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -0,0 +1,45 @@
+name: Release Documentation
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - 'docs-mkdocs'
+      - 'main'
+    paths:
+        - 'docs/**'
+        - '.github/workflows/**'
+  pull_request:
+    branches:
+      - 'main'
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    name: Deploy documentation
+    runs-on: ubuntu-latest
+    steps:
+
+    - name: Checkout code
+      uses: actions/checkout@v3
+      with:
+        sparse-checkout: |
+          .github
+          docs
+
+    - name: Prepare files
+      run: chmod +x docs/mkdocs/prepare-mkdocs.sh && cd docs && ./mkdocs/prepare-mkdocs.sh
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12.2'
+
+    - name: Install mkdocs
+      run: pip install mkdocs-material mkdocs-material[imaging]
+
+    - name: Perform deployment
+      run: cd docs/mkdocs && mkdocs gh-deploy --force
+
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -0,0 +1,49 @@
+# This workflow will build a golang project
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-go
+
+name: Build and Test
+
+# This workflow only runs linter, builds and runs unit tests for development branches.
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - '**'
+      - '!main'
+    paths-ignore:
+      - 'docs/**'  
+  pull_request:
+    branches:
+      - '**'
+      - '!main'
+
+jobs:
+
+  build:
+    name: Build and test project
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v3
+
+    - name: Set up Go
+      uses: actions/setup-go@v4
+      with:
+        go-version: '1.20'
+
+    - name: Preparing
+      run: sudo apt-get -y install libvpx-dev
+
+    - name: Linting
+      run: |
+        cd backend
+        go fmt ./...
+        go vet ./...
+
+    - name: Test
+      run: cd backend && go test -v ./...
+
+    - name: Build
+      run: cd backend && go build -v ./...
diff --git a/README.md b/README.md
@@ -1,5 +1,4 @@
-# **WebRTC Nuts and Bolts**
-
+# <img src="docs/images/icon.svg" width="24"></img> **WebRTC Nuts and Bolts**
 
 [![LinkedIn](https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white&style=flat-square)](https://www.linkedin.com/in/alper-dalkiran/)
 [![Twitter](https://img.shields.io/badge/Twitter-1DA1F2?style=for-the-badge&logo=twitter&logoColor=white&style=flat-square)](https://twitter.com/aalperdalkiran)
@@ -14,31 +13,27 @@ You can track which steps taken during this journey by debugging or tracking the
 
 ![Backend initial output](docs/images/01-07-backend-initial-output.png)
 
-<br>
-
-## **WHY THIS PROJECT?**
+## :thought_balloon: **WHY THIS PROJECT?**
 
 This project was initially started to learn Go language and was made for experimental and educational purposes only, not for production use.
 
 After some progress on the development, I decided to pivot my experimental work to a walkthrough document. Because although there are lots of resources that exist already on the Internet, they cover small chunks of WebRTC concepts or protocols atomically. And they use the standard way of inductive method which teach in pieces then assemble them.
 
 But my style of learning leans on the deductive method instead of others, so instead of learning atomic pieces and concepts first, going linearly from beginning to the end, and learning an atomic piece on the time when learning this piece is required.
 
-<br>
-
-## **DOCUMENTATION**
+## :blue_book: **DOCUMENTATION**
 
-The adventure of a WebRTC stream from start to finish can be found documented as step by step in [docs folder](docs/)
+The adventure of a WebRTC stream from start to finish can be found documented as step by step at [WebRTC Nuts and Bolts - GitHub Pages](https://adalkiran.github.io/webrtc-nuts-and-bolts/) website with a visually better experience, or at [docs directory](./docs/).
 
-<br>
-
-## **COVERAGE**
+## :dart: **COVERAGE**
 
 Web front-end side: Pure TypeScript implementation:
+
 * Communicate with signaling backend WebSocket,
 * Gathering webcam streaming track from browser and send this track to backend via UDP.
 
 Server back-end side: Pure Go language implementation:
+
 * A simple signaling back-end WebSocket to transfer [SDP (Session Description Protocol)](https://en.wikipedia.org/wiki/Session_Description_Protocol) using [Gorilla WebSocket](https://github.com/gorilla/websocket) library.
 * Single port UDP listener, supports demultiplexing different data packet types (STUN, DTLS handshake, SRTP, SRTCP) coming from the same UDP connection.
 * Protocol implementations of (only required parts):
@@ -50,10 +45,7 @@ Server back-end side: Pure Go language implementation:
 * [github.com/fatih/color](https://github.com/fatih/color) was used while printing colored output on console while logging.
 * Implementation of TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 [cipher suite](https://www.keyfactor.com/blog/cipher-suites-explained/) support using [Go Cryptography](https://pkg.go.dev/golang.org/x/crypto) library.
 
-
-<br>
-
-## **INSTALLATION and RUNNING**
+## :package: **INSTALLATION and RUNNING**
 
 This project was designed to run in Docker Container. Docker Compose file creates two containers: webrtcnb-ui and webrtcnb-backend.
 
@@ -97,16 +89,13 @@ Then, follow these steps:
 * After completion of all installations, press <kbd>F5</kbd> to start server application.
 * Then, open a web browser and visit http://localhost:8080 (Tested on Chrome)
 
-<br>
-
-## **ASSUMPTIONS**
+## :bricks: **ASSUMPTIONS**
 
 Full-compliant WebRTC libraries should support a wide range of protocol details defined in RFC documents, client/server implementation differences, fallbacks for different protocol versions, a wide variety of cipher suites and media encoders/decoders. Also should be implemented as state machines, because WebRTC contains has some parts which managed as state machines, eg: [ICE (Interactive Connectivity Establishment)](https://en.wikipedia.org/wiki/Interactive_Connectivity_Establishment), [DTLS (Datagram Transport Layer Security)](https://en.wikipedia.org/wiki/Datagram_Transport_Layer_Security) handshake, etc...
 
-
 In **WebRTC Nuts and Bolts** scenario, some assumptions have been made to focus only on required set of details.
 
-| Full-compliant WebRTC libraries | WebRTC Nuts and Bolts | 
+| Full-compliant WebRTC libraries | WebRTC Nuts and Bolts |
 |---|---|
 | WebRTC has no client or server concepts in its [peer-to-peer](https://tr.wikipedia.org/wiki/Peer-to-peer) nature, there are controlling or controlled peers. | This project aims to act as listener server and it only receives media, not sends. To make the code more simplistic and cleaner; the concepts "client" instead of "local peer" and "server" instead of "remote peer" has been used. |
 | Should support both controlling and controlled roles. | Go language side will act only as server (ICE controlling), SDP offer will come from this side, then SDP answer will be expected from the client. |
@@ -115,9 +104,13 @@ In **WebRTC Nuts and Bolts** scenario, some assumptions have been made to focus
 | Should support multiple cipher suites for compatibility with different types of peers. More cipher suites can be found at [here](https://developers.cloudflare.com/ssl/ssl-tls/cipher-suites/). |  Only TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 is supported. |
 | Should implement packet reply detection, handling corrupted packets, handling unordered packet sequences and packet losses, byte array length checks, lots of security protections against cyberattacks, etc... | This project was developed to run in only ideal conditions. Incoming malicious packets were not considered. |
 
-<br>
+## :star: **CONTRIBUTING and SUPPORTING the PROJECT**
+
+You are welcome to [create issues](https://github.com/adalkiran/webrtc-nuts-and-bolts/issues/new) to report any bugs or problems you encounter. At present, I'm not sure whether this project should be expanded to cover more concepts or not. Only time will tell :blush:.
 
-## **RESOURCES**
+If you liked and found my project helpful and valuable, I would greatly appreciate it if you could give the repo a star :star: on GitHub. Your support and feedback not only help the project improve and grow but also contribute to reaching a wider audience within the community. Additionally, it motivates me to create even more innovative projects in the future.
+
+## :book: **RESOURCES**
 
 I want to thank to contributors of the awesome sources which were referred during development of this project and writing this documentation. You can find these sources below, also in between the lines in code and documentation.
 
@@ -134,8 +127,7 @@ I want to thank to contributors of the awesome sources which were referred durin
 * [Tinydtls](https://github.com/eclipse/tinydtls): A library for DTLS processes, developed in C.
 * [Mozilla Web Docs: WebRTC API](https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API): A documentation on WebRTC API at browser side.
 * Several RFC Documents: In code and documentation of this project, you can find several RFC document links cited.
-<br>
 
-## **LICENSE**
+## :scroll: **LICENSE**
 
-WebRTC Nuts and Bolts is licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for the full license text.
+WebRTC Nuts and Bolts is licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for the full license text.
diff --git a/docs/00-INFRASTRUCTURE.md b/docs/00-INFRASTRUCTURE.md
@@ -5,6 +5,7 @@ When you run the docker-compose.yml file individually (for production mode) or d
 ## **0.1. Container webrtcnb-ui (ui/Dockerfile) is booting up...**
 
 <sup>Related part of [docker-compose.yml](../docker-compose.yml):</sup>
+
 ```yml
 ...
   ui:
@@ -23,6 +24,7 @@ When you run the docker-compose.yml file individually (for production mode) or d
 ```
 
 <sup>Related part of [ui/Dockerfile](../ui/Dockerfile):</sup>
+
 ```dockerfile
 ARG VARIANT=18-bullseye
 FROM mcr.microsoft.com/vscode/devcontainers/typescript-node:0-${VARIANT}
@@ -37,9 +39,11 @@ ENTRYPOINT yarn install && npm run start
 This file inherits from *mcr.microsoft.com/vscode/devcontainers/typescript-node:18-bullseye* image which come up with an environment includes NodeJS, Webpack, Webpack Dev Server, TypeScript, over Debian "Bullseye" Linux Distribution. We don't need to install related things manually.
 
 While building the custom image (once):
+
 * Runs *apt-get update* to update installed OS dependencies
 
 While every time of the container starting up:
+
 * Boots up *webrtcnb-ui* container
 * Maps */ui* directory (in host machine) to */workspace* (in container)
 * Exposes container's *8080* port to the host (so we can browse the website served in the container)
@@ -50,6 +54,7 @@ While every time of the container starting up:
 ## **0.2. Container webrtcnb-backend (backend/Dockerfile) is booting up...**
 
 <sup>Related part of [docker-compose.yml](../docker-compose.yml):</sup>
+
 ```yml
 ...
   backend:
@@ -74,6 +79,7 @@ While every time of the container starting up:
 ```
 
 <sup>Related part of [backend/Dockerfile](../backend/Dockerfile):</sup>
+
 ```dockerfile
 ARG VARIANT=1.20.2-bullseye
 FROM golang:${VARIANT}
@@ -92,12 +98,14 @@ ENTRYPOINT "/entrypoint.sh"
 This file inherits from *golang:1.20.2-bullseye* image which come up with an environment includes Go language support, libraries for processing VP8 (video) and OPUS (audio) encoding, on Debian "Bullseye" Linux Distribution. We don't need to install related things manually.
 
 While building the custom image (once):
+
 * Embeds [entrypoint.sh](../backend/entrypoint.sh) and [entrypoint-dev.sh](../backend/entrypoint-dev.sh) files into the custom image
 * Runs *apt-get update* to update installed OS dependencies
 * Installs [libvpx](https://en.wikipedia.org/wiki/Libvpx) and other codec libraries. Currently we use the libvpx one only.
 * Allows the entrypoint shell script files to be executed.
 
 While every time of the container starting up:
+
 * Boots up *webrtcnb-backend* container
 * Maps */backend* directory (in host machine) to */workspace* (in container)
 * Exposes container's *8081* port to the host (so our browser can access the websocket served in the container)
@@ -106,6 +114,7 @@ While every time of the container starting up:
 * Executes *[entrypoint.sh](../backend/entrypoint.sh)* or *[entrypoint-dev.sh](../backend/entrypoint-dev.sh)* according to which mode (production or development) it runs.
 
 <sup>Related part of [backend/entrypoint.sh](../backend/entrypoint.sh):</sup>
+
 ```sh
 echo "Downloading dependent Go modules..."
 go mod download -x
@@ -115,6 +124,7 @@ go run .
 ```
 
 <sup>Related part of [backend/entrypoint-dev.sh](../backend/entrypoint-dev.sh):</sup>
+
 ```sh
 echo "Downloading dependent Go modules..."
 go mod download -x
@@ -123,6 +133,7 @@ tail -f /dev/null
 ```
 
 * Both entrypoint.sh and entrypoint-dev.sh files call *go mod download -x* to download and install related Go language dependencies defined in [go.mod](../backend/go.mod) (this step can take some time)
+
     * If it is in production mode, it calls
     <br>*go run .*
     <br>to start our server immediately.
@@ -137,6 +148,7 @@ If you followed up related instructions correctly, you can see outputs like thes
 * Checking the containers are running:
 
 Expected output (can vary)
+
 ```console
 $ docker ps
 
@@ -150,6 +162,7 @@ CONTAINER ID   IMAGE                           COMMAND                  CREATED
 If you can see *｢wdm｣: Compiled successfully.* in latest output, it has started serving successfully.
 
 Expected output (can vary) (you can exit by pressing <kbd>CTRL+C</kbd>)
+
 ```console
 $ docker logs -f webrtcnb-ui
 
@@ -181,7 +194,7 @@ webpack 5.72.0 compiled successfully in 4333 ms
 
 If you can see *Running into Waiting loop...* in latest output, it has started successfully and waiting for you to start the server application manually.
 
-```console
+```sh
 $ docker logs -f webrtcnb-backend
 
 Container started