feat(docs): add filecoin subway user guide

[LesnyRumcajs]

Summary of changes

Changes introduced in this pull request:

• added a small guide for Protofire's Subway itnegration with Forest.

Reference issue to close (if applicable)

Closes #6334

Other information and links

Change checklist

• I have performed a self-review of my own code,
• I have made corresponding changes to the documentation. All new code adheres to the team's documentation standards,
• I have added tests that prove my fix is effective or that my feature works (if possible),
• I have made sure the CHANGELOG is up-to-date. All user-facing changes should be reflected in this document.

Summary by CodeRabbit

• Documentation
  • Added comprehensive guides for operating Filecoin nodes behind proxies, including safety considerations, configuration steps, and best practices.
  • New setup documentation for Filecoin Subway proxy integration.
  • Reorganized and enhanced proxy documentation for improved navigation and clarity.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

This change adds documentation for proxy configurations used with Filecoin nodes. It introduces a new "Proxies" guide section containing overview and setup instructions for Filecoin Subway and Lotus Gateway. Additionally, "WebSocket" is added to the documentation dictionary.

Changes

Cohort / File(s)	Summary
Proxy Guide Structure docs/docs/users/guides/proxies/_category_.json	New category configuration file establishing "Proxies" documentation section with position ordering.
Proxy Documentation docs/docs/users/guides/proxies/overview.md, docs/docs/users/guides/proxies/running_with_filecoin_subway.md	New documentation files introducing proxy overview for Filecoin nodes and setup instructions for running Forest with Filecoin Subway, including environment variables and usage examples.
Updated Proxy Guide docs/docs/users/guides/proxies/running_with_gateway.md	Sidebar position updated from 1 to 2; introductory content removed, now starts directly with Lotus Gateway section.
Dictionary Update docs/dictionary.txt	Added "WebSocket" entry to the documentation dictionary.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Suggested reviewers

• hanabi1224
• sudo-shashank

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title 'feat(docs): add filecoin subway user guide' accurately describes the main change: adding documentation for Filecoin Subway integration.
Linked Issues check	✅ Passed	The PR fulfills both completion criteria from issue #6334: it includes documentation for Filecoin Subway integration (running_with_filecoin_subway.md) similar in format to the existing gateway guide.
Out of Scope Changes check	✅ Passed	All changes are within scope: new Subway documentation, supporting category structure, dictionary update, and minor adjustment to gateway guide positioning. No unrelated modifications detected.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/docs/users/guides/proxies/running_with_gateway.md (1)

131-131: Fix typo in comment.

The word "initliazation" should be "initialization".

✏️ Proposed fix

-        # Perform basic initliazation, including generating the JWT token
+        # Perform basic initialization, including generating the JWT token

🧹 Nitpick comments (3)

docs/docs/users/guides/proxies/running_with_gateway.md (1)

106-110: Consider improving the snapshot check logic.

The current condition if [ "$$(ls -A /data/*.car.zst)" ] may not behave as intended. The -A flag lists all entries (including hidden files), and if the glob doesn't match, the command will fail with an error rather than returning empty.

♻️ More robust alternative

-        if [ "$$(ls -A /data/*.car.zst)" ]; then
+        if ls /data/*.car.zst >/dev/null 2>&1; then
           echo "Snapshot already fetched"
         else
           forest-tool snapshot fetch --chain calibnet -d /data
         fi

This approach checks the exit code of ls directly and suppresses both stdout and stderr, making it more reliable when files don't exist.

docs/docs/users/guides/proxies/running_with_filecoin_subway.md (1)

27-27: Improve link text for better accessibility.

The link text "here" is not descriptive. Consider using text that describes the destination, such as "in the eth_config.yml file" or "eth_config.yml configuration".

♻️ Proposed improvement

-- `configs/eth_config.yml` is the configuration file for Filecoin Subway. You can modify it to suit your needs. This configuration file is included in the Filecoin Subway repository [here](https://github.com/protofire/filecoin-subway/blob/chain/filecoin/configs/eth_config.yml).
+- `configs/eth_config.yml` is the configuration file for Filecoin Subway. You can modify it to suit your needs. This configuration file is included in the [Filecoin Subway repository](https://github.com/protofire/filecoin-subway/blob/chain/filecoin/configs/eth_config.yml).

Or alternatively:

-- `configs/eth_config.yml` is the configuration file for Filecoin Subway. You can modify it to suit your needs. This configuration file is included in the Filecoin Subway repository [here](https://github.com/protofire/filecoin-subway/blob/chain/filecoin/configs/eth_config.yml).
+- `configs/eth_config.yml` is the configuration file for Filecoin Subway. You can modify it to suit your needs. View the [eth_config.yml file in the repository](https://github.com/protofire/filecoin-subway/blob/chain/filecoin/configs/eth_config.yml).

docs/docs/users/guides/proxies/overview.md (1)

12-12: Consider more specific language (optional).

The phrase "very expensive" could be replaced with more precise terminology like "computationally expensive" or "resource-intensive" for greater clarity.

♻️ Suggested alternative

-Certain methods are very expensive and can potentially be abused. The current JWT protection mechanism has only mutability checks.
+Certain methods are computationally expensive and can potentially be abused. The current JWT protection mechanism has only mutability checks.

📜 Review details

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between b10e85c and c296871.

📒 Files selected for processing (5)

• docs/dictionary.txt
• docs/docs/users/guides/proxies/_category_.json
• docs/docs/users/guides/proxies/overview.md
• docs/docs/users/guides/proxies/running_with_filecoin_subway.md
• docs/docs/users/guides/proxies/running_with_gateway.md

🧰 Additional context used

🧠 Learnings (1)

📓 Common learnings

Learnt from: LesnyRumcajs
Repo: ChainSafe/forest PR: 5907
File: src/rpc/methods/state.rs:523-570
Timestamp: 2025-08-06T15:44:33.467Z
Learning: LesnyRumcajs prefers to rely on BufWriter's Drop implementation for automatic flushing rather than explicit flush() calls in Forest codebase.

🪛 LanguageTool

docs/docs/users/guides/proxies/overview.md

[style] ~12-~12: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...e reasons include: Certain methods are very expensive and can potentially be abused. The curr...

(EN_WEAK_ADJECTIVE)

🪛 markdownlint-cli2 (0.18.1)

docs/docs/users/guides/proxies/running_with_filecoin_subway.md

27-27: Link text should be descriptive

(MD059, descriptive-link-text)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: rubocop

🔇 Additional comments (5)

docs/dictionary.txt (1)

158-158: LGTM! Correct dictionary addition.

The "WebSocket" entry is appropriately added and correctly positioned alphabetically, supporting the new proxy documentation.

docs/docs/users/guides/proxies/_category_.json (1)

1-4: LGTM! Proper category structure.

The category configuration follows standard Docusaurus conventions and appropriately organizes the new proxy documentation section.

docs/docs/users/guides/proxies/running_with_gateway.md (1)

3-3: LGTM! Correct sidebar positioning.

The sidebar_position change from 1 to 2 appropriately places the gateway guide after the overview page.

docs/docs/users/guides/proxies/running_with_filecoin_subway.md (1)

1-38: Well-structured documentation!

The Filecoin Subway guide is clear, concise, and provides practical examples. The environment variables are well-explained, and the websocat example demonstrates how to test the setup effectively.

docs/docs/users/guides/proxies/overview.md (1)

1-18: Excellent overview!

The proxy overview effectively communicates the security and operational concerns of directly exposing a Filecoin node's RPC interface. The rationale is clear and well-structured.

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}