Merge remote-tracking branch 'origin/main' into ipfs-web

* origin/main: (24 commits)
  Revert "edit problematic file"
  fix: use offical action now that pr has been merged
  edit problematic file
  fix: use forked langauge tool action
  ci: review prs with languagetool
  chore: bump versions in installation docs (#1958)
  Update docs/how-to/gateway-troubleshooting.md
  add blockchain to list of accepted words
  fix vale error
  add reprovide to accepted words
  correct dht expiration time for records
  correct dht expiration time and improve ipns docs
  fix: update pinning services
  Update merkle-dag.md
  fix: formatting
  Update docs/concepts/ipfs-implementations.md
  chore: use current-ipfs-version
  fix: lint
  docs: docker container limits
  change helia language to TS
  ...

Author: 2color

.github/styles/Vocab/ipfs-docs-vocab/accept.txt

@@ -1,3 +1,4 @@
+atcute
 (?i)APIs?
 (?i)BitSwap
 (?i)CIDs?
@@ -36,6 +37,7 @@
 [Kk]ademlia
 [Kk]eystores?
 [Kk]ubo
+[L]ibipld
 [Mm]arkdown(lint)?
 [Mm]ultiaddr(ess)?
 [Mm]ultiaddrs
@@ -62,6 +64,7 @@ Arbol('s)?
 auditable
 Audius
 auspinner
+blockchain
 blockstore
 Browserify
 callouts?
@@ -167,7 +170,8 @@ Qm
 rasterio
 READMEs?
 referenceable
-reprovider
+reprovide
+reprovide(r)
 reproviding
 retrievability
 roadmaps

.github/styles/pln-ignore.txt

@@ -1,3 +1,4 @@
+atcute
 aave
 accessor
 acls
@@ -121,6 +122,7 @@ lastbootstrap
 lastpeer
 leveldb
 libp2p
+libipld
 linux
 lookups
 loopback
@@ -198,6 +200,8 @@ reproviding
 requesters
 retrievability
 roadmaps
+runtime
+runtime's
 rsa
 sandboxed
 satoshi

.github/workflows/reveiwdog-languagetool.yml

@@ -0,0 +1,19 @@
+name: Check Spelling
+on:
+  pull_request:
+    paths:
+      - 'docs/**/*.md'
+jobs:
+  languagetool:
+    name: languagetool
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check Spelling
+        uses: reviewdog/action-languagetool@v1
+        with:
+          github_token: ${{ secrets.github_token }}
+          reporter: github-pr-review
+          level: info
+          patterns: 'docs/**/*.md'
+

docs/concepts/ipfs-implementations.md

@@ -33,6 +33,8 @@ Yet, there are many situations where content-addressed data needs to be regularl
 
 The InterPlanetary Name System (IPNS) is a system for creating such mutable pointers to CIDs known as **names** or **IPNS names**. IPNS names can be thought of as links that can be updated over time, while retaining the verifiability of content addressing.
 
+By analogy, IPNS names are like tags in git, which can be updated over time, and CIDs are like commit hashes in Git, which point to a snapshot of the files in the repository.
+
 ::: callout
 An IPNS name can point to any arbitrary content path (`/ipfs/` or `/ipns/`), *including another IPNS name or DNSLink path*. However, it most commonly points to a fully resolved and immutable path, i.e. `/ipfs/[CID]`.
 :::
@@ -121,7 +123,7 @@ The main implication of this difference is that IPNS operations (publishing and
 
 The DHT is the default transport mechanism for IPNS records in many IPFS implementations.
 
-Due to the ephemeral nature of the DHT, peers forget records after 24 hours. This applies to any record in the DHT, irrespective of the `validity` (also referred to as `lifetime`) field in the IPNS record.
+Due to the ephemeral nature of the DHT, records expire [after 48 hours](https://github.com/libp2p/specs/tree/b5f7fce29b32d4c7d0efe37b019936a11e5db872/kad-dht#content-provider-advertisement-and-discovery). This applies to any record in the DHT, irrespective of the `validity` (also referred to as `lifetime`) field in the IPNS record.
 
 Therefore, IPNS records need to be regularly (re-)published to the DHT. Moreover, publishing to the DHT at regular intervals ensures that the IPNS name can be resolved even when there's high node churn (nodes coming and going.)
 
@@ -173,7 +175,7 @@ Availability means resolving to a valid IPNS record, at the cost of potentially
 
 #### IPNS record validity
 
-When setting the `validity` (referred to as [`lifetime` by Kubo](https://github.com/ipfs/kubo/blob/master/docs/config.md#ipnsrecordlifetime)) field of an IPNS record, you typically need to choose whether you favor **consistency** (short validity period, e.g. 24 hours) or **availability** (long validity period, e.g. 1 month), due to the inherent trade-off between the two.
+When setting the `validity` (referred to as [`lifetime` by Kubo](https://github.com/ipfs/kubo/blob/master/docs/config.md#ipnsrecordlifetime)) field of an IPNS record, you typically need to choose whether you favor **consistency** (short validity period, e.g. 48 hours) or **availability** (long validity period, e.g. 1 month), due to the inherent trade-off between the two.
 
 #### Practical considerations
 

docs/concepts/ipns.md

@@ -13,7 +13,7 @@ A Merkle DAG is a DAG where each node has an identifier, and this is the result
 
 - Merkle DAGs can only be constructed from the leaves, that is, from nodes without children. Parents are added after children because the children's identifiers must be computed in advance to be able to link them.
 - Every node in a Merkle DAG is the root of a (sub)Merkle DAG itself, and this subgraph is _contained_ in the parent DAG.
-- Merkle DAG nodes are _immutable_. Any change in a node would alter its identifier and thus affect all the ascendants in the DAG, essentially creating a different DAG. Take a look at [this helpful illustration using bananas](https://media.consensys.net/ever-wonder-how-merkle-trees-work-c2f8b7100ed3) from our friends at Consensys.
+- Merkle DAG nodes are _immutable_. Any change in a node would alter its identifier and thus affect all the ascendants in the DAG, essentially creating a different DAG.
 
 Merkle DAGs are similar to Merkle trees, but there are no balance requirements, and every node can carry a payload. In DAGs, several branches can re-converge or, in other words, a node can have several parents.
 

docs/concepts/merkle-dag.md

@@ -106,7 +106,7 @@ If providers were found in the DHT, do the following:
 
 ### No providers returned
 
-If no providers are returned, the issue may lie in the content publishing lifecycle, specifically _reprovider runs_, the continuous process in which a node advertises provider records. _Provider records_ are mappings of CIDs to network addresses, and have an expiration time of 24 hours, which accounts for provider churn. Generally speaking, as more files are added to an IPFS node, the longer reprovide runs take. When a reprovide run takes longer than 24 hours (the expiration time for provider records), CIDs will no longer be discoverable.
+If no providers are returned, the issue may lie in the content publishing lifecycle, specifically _reprovider runs_, the continuous process in which a node advertises provider records. _Provider records_ are mappings of CIDs to network addresses, and have an expiration time of 48 hours, which accounts for provider churn. Generally speaking, as more files are added to an IPFS node, the longer reprovide runs take. When a reprovide run takes longer than 48 hours (the expiration time for provider records), CIDs will no longer be discoverable.
 
 :::
 You can learn more about the content publishing lifecycle in [How IPFS works](../concepts/how-ipfs-works.md).
@@ -129,16 +129,16 @@ With this in mind, if no providers are returned, do the following:
    LastReprovideBatchSize: 1k (1,858)
    ```
 
-1. Note the value for `LastReprovideDuration`. If it is close to 24 hours, select one of the following options, keeping in mind that each has tradeoffs:
+2. Note the value for `LastReprovideDuration`. If it is close to 48 hours, select one of the following options, keeping in mind that each has tradeoffs:
 
    - **Enable the [Accelerated DHT Client](https://github.com/ipfs/go-ipfs/blob/master/docs/experimental-features.md#accelerated-dht-client) in Kubo**. This configuration improves content publishing times significantly by maintaining more connections to peers and a larger routing table and batching advertising of provider records. However, this performance boost comes at the cost of increased resource consumption.
 
    - **Change the reprovider strategy from `all` to either `pinned` or `roots`.** In both cases, only provider records for explicitly pinned content are advertised. Differences and tradeoffs are noted below:
       - The `pinned` strategy will advertise both the root CIDs and child block CIDs (the entire DAG) of explicitly pinned content.
       - The `roots` strategy will only advertise the root CIDs of pinned content, reducing the total number of provides in each run. This strategy is the most efficient, but should be done with caution, as it will limit discoverability only to root CIDs. In other words, if you are adding folders of files to an IPFS node, only the CID for the pinned folder will be advertised. All the blocks will still be retrievable with Bitswap once a connection to the node is established.
 
-1. Manually trigger a reprovide run:
+3. Manually trigger a reprovide run:
 
    ```shell
    ipfs bitswap reprovide
-   ```
+   ```

docs/how-to/gateway-troubleshooting.md

@@ -44,8 +44,7 @@ Third-party pinning services allow you to purchase pinning capacity for importan
 
 - [Pinata](https://pinata.cloud/)
 - [Filebase](https://filebase.com/)
-- [Temporal](https://temporal.cloud/)
-- [Crust](https://crust.network/)
+- [Storacha (formerly web3.storage)](https://storacha.network/)
 - [Infura](https://infura.io/)
 - [Scaleway](https://labs.scaleway.com/en/ipfs-pinning/)
 

docs/how-to/work-with-pinning-services.md

@@ -1,7 +1,7 @@
 ---
 title: Kubo
 description: Using IPFS Kubo through the command-line allows you to do everything that IPFS Desktop can do, but at a more granular level, since you can specify which commands to run. Learn how to install it here.
-current-ipfs-version: v0.32.1
+current-ipfs-version: v0.33.0
 ---
 
 # Install IPFS Kubo
@@ -31,7 +31,7 @@ Kubo runs on most Windows, MacOS, Linux, FreeBSD and OpenBSD systems that meet t
 
 Note the following:
 - The amount of disk space your IPFS installation uses depends on how much data you're sharing. A base installation uses around 12MB of disk space.
-- You can enable automatic garbage collection via [--enable-gc](../reference/kubo/cli.md#ipfs-daemon) and adjust using [default maximum disk storage](https://github.com/ipfs/kubo/blob/v0.32.1/docs/config.md#datastorestoragemax) for data retrieved from other peers.
+- You can enable automatic garbage collection via [--enable-gc](../reference/kubo/cli.md#ipfs-daemon) and adjust using [default maximum disk storage](https://github.com/ipfs/kubo/blob/v0.33.0/docs/config.md#datastorestoragemax) for data retrieved from other peers.
 
 
 <!-- TODO: hide this footgun until https://github.com/ipfs/kubo/pull/10524 is merged and released in stable kubo 
@@ -76,27 +76,27 @@ For installation instructions for your operating system, select the appropriate
 1. Download the Windows binary from [`dist.ipfs.tech`](https://dist.ipfs.tech/#kubo).
 
    ```powershell
-   wget https://dist.ipfs.tech/kubo/v0.32.1/kubo_v0.32.1_windows-amd64.zip -Outfile kubo_v0.32.1.zip
+   wget https://dist.ipfs.tech/kubo/v0.33.0/kubo_v0.33.0_windows-amd64.zip -Outfile kubo_v0.33.0.zip
    ```
 
-1. Unzip the file to a sensible location, such as `~\Apps\kubo_v0.32.1`.
+1. Unzip the file to a sensible location, such as `~\Apps\kubo_v0.33.0`.
 
    ```powershell
-   Expand-Archive -Path kubo_v0.32.1.zip -DestinationPath ~\Apps\kubo_v0.32.1
+   Expand-Archive -Path kubo_v0.33.0.zip -DestinationPath ~\Apps\kubo_v0.33.0
    ```
 
-1. Move into the `kubo_v0.32.1` folder
+1. Move into the `kubo_v0.33.0` folder
 
    ```powershell
-   cd ~\Apps\kubo_v0.32.1\kubo
+   cd ~\Apps\kubo_v0.33.0\kubo
    ```
 
 1. Check that the `ipfs.exe` works:
 
    ```powershell
    .\ipfs.exe --version
 
-   > ipfs version 0.32.1
+   > ipfs version 0.33.0
    ```
 
    At this point, Kubo is usable. However, it's strongly recommended that you first add `ipfs.exe` to your `PATH` using the following steps:
@@ -142,7 +142,7 @@ For installation instructions for your operating system, select the appropriate
    ```powershell
    ipfs --version
 
-   > ipfs version 0.32.1
+   > ipfs version 0.33.0
    ```
 
 :::
@@ -170,7 +170,7 @@ For installation instructions for your operating system, select the appropriate
    If Kubo is installed, the version number displays. For example:
 
    ```bash
-   > ipfs version 0.32.1
+   > ipfs version 0.33.0
    ```
 :::
 
@@ -181,13 +181,13 @@ For installation instructions for your operating system, select the appropriate
 1. Download the Linux binary from [`dist.ipfs.tech`](https://dist.ipfs.tech/#kubo).
 
    ```bash
-   wget https://dist.ipfs.tech/kubo/v0.32.1/kubo_v0.32.1_linux-amd64.tar.gz
+   wget https://dist.ipfs.tech/kubo/v0.33.0/kubo_v0.33.0_linux-amd64.tar.gz
    ```
 
 1. Unzip the file:
 
    ```bash
-   tar -xvzf kubo_v0.32.1_linux-amd64.tar.gz
+   tar -xvzf kubo_v0.33.0_linux-amd64.tar.gz
 
    > x kubo/install.sh
    > x kubo/ipfs
@@ -216,7 +216,7 @@ For installation instructions for your operating system, select the appropriate
    ```bash
    ipfs --version
 
-   > ipfs version 0.32.1
+   > ipfs version 0.33.0
    ```
 
 :::
@@ -228,13 +228,13 @@ For installation instructions for your operating system, select the appropriate
 1. Download the FreeBSD binary from [`dist.ipfs.tech`](https://dist.ipfs.tech/#kubo).
 
    ```bash
-   wget https://dist.ipfs.tech/kubo/v0.32.1/kubo_v0.32.1_freebsd-amd64.tar.gz
+   wget https://dist.ipfs.tech/kubo/v0.33.0/kubo_v0.33.0_freebsd-amd64.tar.gz
    ```
 
 1. Unzip the file:
 
    ```bash
-   tar -xvzf kubo_v0.32.1_freebsd-amd64.tar.gz
+   tar -xvzf kubo_v0.33.0_freebsd-amd64.tar.gz
 
    > x kubo/install.sh
    > x kubo/ipfs
@@ -263,7 +263,7 @@ For installation instructions for your operating system, select the appropriate
    ```bash
    ipfs --version
 
-   > ipfs version 0.32.1
+   > ipfs version 0.33.0
    ```
 
 :::
@@ -275,13 +275,13 @@ For installation instructions for your operating system, select the appropriate
 1. Download the OpenBSD binary from [`dist.ipfs.tech`](https://dist.ipfs.tech/#kubo).
 
    ```bash
-   wget https://dist.ipfs.tech/kubo/v0.32.1/kubo_v0.32.1_openbsd-amd64.tar.gz
+   wget https://dist.ipfs.tech/kubo/v0.33.0/kubo_v0.33.0_openbsd-amd64.tar.gz
    ```
 
 1. Unzip the file:
 
    ```bash
-   tar -xvzf kubo_v0.32.1_openbsd-amd64.tar.gz
+   tar -xvzf kubo_v0.33.0_openbsd-amd64.tar.gz
 
    > x kubo/install.sh
    > x kubo/ipfs
@@ -310,7 +310,7 @@ For installation instructions for your operating system, select the appropriate
    ```bash
    ipfs --version
 
-   > ipfs version 0.32.1
+   > ipfs version 0.33.0
    ```
 
 :::
@@ -322,7 +322,7 @@ For installation instructions for your operating system, select the appropriate
 
 ## Build Kubo from source
 
-For the current instructions on how to manually download, compile and build Kubo from source, see the [Build from Source](https://github.com/ipfs/kubo/blob/v0.32.1/README.md#build-from-source) section in the Kubo repository.
+For the current instructions on how to manually download, compile and build Kubo from source, see the [Build from Source](https://github.com/ipfs/kubo/blob/v0.33.0/README.md#build-from-source) section in the Kubo repository.
 
 ## Determining which node to use with the command line
 

docs/install/command-line.md

@@ -1,6 +1,7 @@
 ---
 title: Install IPFS Kubo inside Docker
 description: You can run IPFS inside Docker to simplify your deployment processes, and horizontally scale your IPFS infrastructure.
+current-ipfs-version: v0.33.0
 ---
 
 # Install IPFS Kubo inside Docker
@@ -20,7 +21,7 @@ You can run Kubo IPFS inside Docker to simplify your deployment processes, as we
 1. Start a container running ipfs and expose ports `4001` (P2P TCP/QUIC transports), `5001` (RPC API) and `8080` (Gateway):
 
     ```shell
-    docker run -d --name ipfs_host -v $ipfs_staging:/export -v $ipfs_data:/data/ipfs -p 4001:4001 -p 4001:4001/udp -p 127.0.0.1:8080:8080 -p 127.0.0.1:5001:5001 ipfs/kubo:latest
+    docker run -d --name ipfs_host -v $ipfs_staging:/export -v $ipfs_data:/data/ipfs -p 4001:4001 -p 4001:4001/udp -p 127.0.0.1:8080:8080 -p 127.0.0.1:5001:5001 ipfs/kubo:v0.33.0
     ```
 
     ::: danger NEVER EXPOSE THE RPC API TO THE PUBLIC INTERNET
@@ -70,7 +71,7 @@ You can run Kubo IPFS inside Docker to simplify your deployment processes, as we
 When starting a container running ipfs for the first time with an empty data directory, it will call `ipfs init` to initialize configuration files and generate a new keypair. At this time, you can choose which profile to apply using the `IPFS_PROFILE` environment variable:
 
 ```shell
-docker run -d --name ipfs_host -e IPFS_PROFILE=server -v $ipfs_staging:/export -v $ipfs_data:/data/ipfs -p 4001:4001 -p 4001:4001/udp -p 127.0.0.1:8080:8080 -p 127.0.0.1:5001:5001 ipfs/kubo:latest
+docker run -d --name ipfs_host -e IPFS_PROFILE=server -v $ipfs_staging:/export -v $ipfs_data:/data/ipfs -p 4001:4001 -p 4001:4001/udp -p 127.0.0.1:8080:8080 -p 127.0.0.1:5001:5001 ipfs/kubo:v0.33.0
 ```
 
 ## Customizing your node
@@ -105,19 +106,35 @@ docker run -d --name ipfs \
 See the `gateway` example on the [go-ipfs-docker-examples repository](https://github.com/ipfs-shipyard/go-ipfs-docker-examples)
 :::
 
+## Configuring resource limits
+
+When deploying IPFS Kubo in containerized environments, it's crucial to align the Go runtime's resource awareness with the container's defined resource constraints via environment variables:
+
+- `GOMAXPROCS`: Configures the maximum number of OS threads that can execute Go code concurrently (should not be bigger than the hard container limit set via `docker --cpus`)
+- `GOMEMLIMIT`: Sets the soft [memory allocation limit for the Go runtime](https://tip.golang.org/doc/gc-guide#Memory_limit) (should be slightly below the hard limit set for container via `docker --memory`)
+
+Example:
+
+```shell
+docker run # (....)
+    --cpus="4.0" -e GOMAXPROCS=4 \
+    --memory="8000m" -e GOMEMLIMIT=7500MiB \
+    ipfs/kubo:v0.33.0
+```
+
 ## Private swarms inside Docker
 
 It is possible to initialize the container with a swarm key file (`/data/ipfs/swarm.key`) using the variables `IPFS_SWARM_KEY` and `IPFS_SWARM_KEY_FILE`. The `IPFS_SWARM_KEY` creates `swarm.key` with the contents of the variable itself, while `IPFS_SWARM_KEY_FILE` copies the key from a path stored in the variable. The `IPFS_SWARM_KEY_FILE` **overwrites** the key generated by `IPFS_SWARM_KEY`.
 
 ```shell
-docker run -d --name ipfs_host -e IPFS_SWARM_KEY=<your swarm key> -v $ipfs_staging:/export -v $ipfs_data:/data/ipfs -p 4001:4001 -p 4001:4001/udp -p 127.0.0.1:8080:8080 -p 127.0.0.1:5001:5001 ipfs/kubo:latest
+docker run -d --name ipfs_host -e IPFS_SWARM_KEY=<your swarm key> -v $ipfs_staging:/export -v $ipfs_data:/data/ipfs -p 4001:4001 -p 4001:4001/udp -p 127.0.0.1:8080:8080 -p 127.0.0.1:5001:5001 ipfs/kubo:v0.33.0
 ```
 
 The swarm key initialization can also be done using docker secrets, and requires `docker swarm` or `docker-compose`:
 
 ```shell
 cat your_swarm.key | docker secret create swarm_key_secret -
-docker run -d --name ipfs_host --secret swarm_key_secret -e IPFS_SWARM_KEY_FILE=/run/secrets/swarm_key_secret -v $ipfs_staging:/export -v $ipfs_data:/data/ipfs -p 4001:4001 -p 4001:4001/udp -p 127.0.0.1:8080:8080 -p 127.0.0.1:5001:5001 ipfs/kubo:latest
+docker run -d --name ipfs_host --secret swarm_key_secret -e IPFS_SWARM_KEY_FILE=/run/secrets/swarm_key_secret -v $ipfs_staging:/export -v $ipfs_data:/data/ipfs -p 4001:4001 -p 4001:4001/udp -p 127.0.0.1:8080:8080 -p 127.0.0.1:5001:5001 ipfs/kubo:v0.33.0
 ```
 
 ## Key rotation inside Docker
@@ -126,10 +143,10 @@ It is possible to do key rotation in an ephemeral container that is temporarily
 
 ```shell
 # given container named 'ipfs-test' that persists repo at /path/to/persisted/.ipfs
-docker run -d --name ipfs-test -v /path/to/persisted/.ipfs:/data/ipfs ipfs/kubo:latest
+docker run -d --name ipfs-test -v /path/to/persisted/.ipfs:/data/ipfs ipfs/kubo:v0.33.0
 docker stop ipfs-test  
 
 # key rotation works like this (old key saved under 'old-self')
-docker run --rm -it -v /path/to/persisted/.ipfs:/data/ipfs ipfs/kubo:latest key rotate -o old-self -t ed25519
+docker run --rm -it -v /path/to/persisted/.ipfs:/data/ipfs ipfs/kubo:v0.33.0 key rotate -o old-self -t ed25519
 docker start ipfs-test # will start with the new key
 ```