Adds docs related to using magnet links and torrent files to download content

10 Notes/Magnet Links.md

@@ -26,7 +26,7 @@ magnet:?xt=urn:btmh:122003ee5d27d20f46c2395fb00e407a85f87c885e2e072d01f4e4bc5164
 **Hybrid**
 
 ```
-magnet:?xt=urn:btmh:122003ee5d27d20f46c2395fb00e407a85f87c885e2e072d01f4e4bc516474203fe1&urn:btih:1902d602db8c350f4f6d809ed01eff32f030da95
+magnet:?xt=urn:btmh:122003ee5d27d20f46c2395fb00e407a85f87c885e2e072d01f4e4bc516474203fe1&xt=urn:btih:1902d602db8c350f4f6d809ed01eff32f030da95
 ```
 
 `122003ee5d27d20f46c2395fb00e407a85f87c885e2e072d01f4e4bc516474203fe1` is a SHA-256 multihash:

10 Notes/PR 1179 - checked exceptions in stores.md

@@ -0,0 +1,36 @@
+---
+tags:
+  - codex/pulls
+related-to:
+  - "[[Codex PRs]]"
+---
+https://github.com/codex-storage/nim-codex/pull/1179
+
+Two things to be handled in the follow up PR:
+
+- better signalization in the test `Should propagate cancellation error immediately` in `tests/codex/utils/testsafeasynciter.nim`. See the review comment https://github.com/codex-storage/nim-codex/pull/1179#discussion_r2100831743
+- check what to do with `Error: Exception can raise an unlisted exception: Exception` - see discussion in  https://github.com/codex-storage/nim-codex/pull/1179#discussion_r2100873891
+
+For reference, here is the essence of the `Error: Exception can raise an unlisted exception: Exception` thing:
+
+```nim
+import pkg/chronos
+# the problem does not occur when using std/asyncdispatch
+# import std/asyncdispatch
+
+# without "raises: []" it fails with "Error: Exception can raise an unlisted exception: Exception"
+#func getIter(): (iterator (): int {.gcsafe.}) =
+func getIter(): (iterator (): int {.gcsafe, raises: [].}) =
+  return iterator (): int =
+    yield 1
+    yield 2
+    yield 3
+
+proc f1() =
+  let iter = getIter()
+
+  proc genNext(): Future[int] {.async.} =
+    iter()
+```
+
+See also https://github.com/nim-lang/Nim/issues/3772.

10 Notes/Upload and download BitTorrent content with Codex - demo.md

@@ -11,10 +11,10 @@ task codex, "build codex binary":
 
 In the example session, we will use two nodes:
 
-- node-1 will be where we will upload (seed) the content
-- node-2 will be from where we will be downloading the previously uploaded content.
+- `node-1` will be where we will upload (seed) the content
+- `node-2` will be from where we will be downloading the previously uploaded content.
 
-Start node-1:
+Start `node-1`:
 
 ```bash
 ./build/codex --data-dir=./data-1 --listen-addrs=/ip4/127.0.0.1/tcp/8081 --api-port=8001 --nat=none --disc-port=8091 --log-level=TRACE
@@ -27,7 +27,7 @@ Generate fresh content:
 dd if=/dev/urandom of=./data10M.bin bs=10M count=1
 ```
 
-Upload content to node-1:
+Upload content to `node-1`:
 
 ```bash
 curl -X POST \
@@ -45,15 +45,21 @@ Set `info_hash` env var:
 export INFO_HASH=11144249FFB943675890CF09342629CD3782D107B709
 ```
 
-Start node-2:
+Or if you want to use a magnet file, create a (text) file (e.g. `magnet-v1-test.txt`) and make sure you include your INFO hash it. The response returned after uploading the content is a multihash. To get a regular hash, you just have to skip the first 4 characters:
+
+```
+magnet:?xt=urn:btih:4249FFB943675890CF09342629CD3782D107B709
+```
+
+Start `node-2`:
 
 ```bash
 ./build/codex --data-dir=./data-2 --listen-addrs=/ip4/127.0.0.1/tcp/8082 --api-port=8002 --nat=none --disc-port=8092 --log-level=TRACE
 ```
 
-Make sure that node-1 and node-2 are connect (should be automatic but sometimes we need to trigger it when running on localhost without nat).
+Now, let's make sure that `node-1` and `node-2` are connected.
 
-Get the peerId from node-1
+Get the peerId from `node-1`
 
 ```bash
 curl -H 'Accept: text/plain' 'http://localhost:8001/api/codex/v1/peerid' --write-out '\n'
@@ -66,7 +72,7 @@ Here it is also good to use env var:
 export PEERID_NODE1=$(curl -H 'Accept: text/plain' 'http://localhost:8001/api/codex/v1/peerid')
 ```
 
-Connect node-2 to node-1:
+Connect `node-2` to `node-1`:
 
 ```bash
 curl "http://localhost:8002/api/codex/v1/connect/${PEERID_NODE1}?addrs=/ip4/127.0.0.1/tcp/8081"
@@ -79,12 +85,35 @@ Make sure `INFO_HASH` env var is set:
 export INFO_HASH=11144249FFB943675890CF09342629CD3782D107B709
 ```
 
-Stream the content from node-2:
+Stream the content from `node-2` using `INFO_HASH` directly use: 
 
 ```bash
 curl "http://localhost:8002/api/codex/v1/torrent/${INFO_HASH}/network/stream" -o "${INFO_HASH}.bin"
 ```
 
+and to stream the content from `node-2` using the magnet link, use:
+
+```bash
+curl -X POST \
+  http://localhost:8001/api/codex/v1/torrent/magnet \
+  -H 'Content-Type: text/plain' \
+  -w '\n' \
+  -T magnet-v1-test.txt \
+  -o magnet-v1-content.bin
+```
+(you can change the name under which the downloaded content will be saved, here it is `magnet-v1-content.bin`).
+
+To use magnet links, you do not have to create a file. You can just directly paste the magnet link text as follows:
+
+```bash
+curl -X POST \
+  http://localhost:8001/api/codex/v1/torrent/magnet \
+  -H 'Content-Type: text/plain' \
+  -w '\n' \
+  -d 'magnet:?xt=urn:btih:4249FFB943675890CF09342629CD3782D107B709' \
+  -o magnet-v1-content.bin
+```
+
 And to get just the torrent manifest:
 
 ```bash
@@ -147,7 +176,10 @@ curl "http://localhost:8002/api/codex/v1/torrent/${INFO_HASH}/network/manifest"
 }
 ```
 
-And here is the streaming log (node-2) for the reference:
+You can also use a torrent file when downloading the content from the Codex network. Please check [[Using Torrent Files to Download Content from the Codex Network]].
+### Appendix
+
+The streaming log (node-2) for the reference:
 
 ```bash
 TRC 2025-03-20 03:32:28.939+01:00 torrent requested:                         topics="codex restapi" tid=6977524 multihash=sha1/04010165844CF71179B42AC3C0462E31EB9E74B1

10 Notes/Using Python on macOS.md

@@ -0,0 +1,52 @@
+There are some [[Modern Python Tools]], but I tend to rely on the good old [pyenv](https://github.com/pyenv/pyenv) and native python environments.
+
+### Python Version
+
+I use `pyenv` to switch between python versions.
+I installed it with:
+
+```bash
+brew install pyenv
+```
+
+Using `pyenv` is convenient.
+
+You can check existing versions with:
+
+```bash
+# checks the most recent available version starting with 3
+pyenv latest -k 3
+
+# checks the most recent available version starting with 3.12
+pyenv latest -k 3.12
+```
+
+Now to install the chosen python version, just run:
+
+```bash
+pyenv install 3.13.1
+```
+
+When you run a Python command, `pyenv` will look for a `.python-version` file in the current directory and each parent directory. If no such file is found in the tree, `pyenv` will use the global Python version specified with `pyenv global`. A version specified with the `PYENV_VERSION` environment variable takes precedence over local and global versions.
+
+Run `pyenv versions` for a list of available Python versions. To read more, run `pyenv local --help`.
+
+Running `pyenv local 3.13.1` will create the `.python-version` file in the current directory.
+
+### Python Environment
+
+On my Mac I keep python environments in `~/python-venvs`. Now to create a new environment, run:
+
+```bash
+python -m venv ~/python-venvs/<name-of-the-environment>
+```
+
+To activate and deactivate given python environment, run:
+
+```bash
+# to activate
+source ~/python-venvs/<name-of-the-environment>/bin/activate
+
+# to deactivate 
+deactivate
+```