📒 docs: clarify prefork security model and OS-specific socket behavior by gaby · Pull Request #4240 · gofiber/fiber

gaby · 2026-04-26T18:22:15Z

Motivation

Make prefork documentation explicit about differing OS socket semantics so operators understand platform and threat-model differences.
Surface risk that prefork relaxes single-owner port assumptions and can expose traffic or binding races in shared-host/multi-tenant environments.
Provide actionable operator guidance (service account, container/VM isolation, avoid shared namespaces) and a clear recommendation to disable prefork when strict single-owner port semantics are required.

Description

Updated docs/extra/internal.md to distinguish Linux SO_REUSEPORT semantics from Windows SO_REUSEADDR fallback and clarified platform-dependent binding behavior.
Added a new Security Considerations subsection in docs/extra/internal.md describing local co-resident attacker risk, privilege/user-boundary assumptions, and deployment hardening guidance.
Mirrored the OS distinction and security/hardening guidance in docs/api/fiber.md under the Prefork section and added an explicit recommendation to run without prefork if strict single-owner port semantics are required.
Small wording/flow updates to the prefork workflow to call out Linux vs Windows behavior and operator responsibilities.

Testing

Ran make generate and it completed successfully.
Ran make betteralign, make modernize, and make format and each completed successfully.
Ran make lint and it completed successfully.
Ran make test and the full test suite completed successfully (PASS for all tests except 1 skipped).
Ran make audit and it failed due to govulncheck findings in the Go standard library for the toolchain go1.25.1 (multiple standard-library vulnerabilities were reported by the vulnerability scanner), which are unrelated to this documentation-only change.

Codex Task

coderabbitai · 2026-04-26T18:22:22Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: b3b4bed9-7101-42e5-985b-4601275a562c

📥 Commits

Reviewing files that changed from the base of the PR and between 2d9b63c and c772a44.

📒 Files selected for processing (1)

docs/api/fiber.md

Walkthrough

This PR updates Prefork documentation to clarify OS-specific socket semantics (Linux typically uses SO_REUSEPORT; Windows uses a SO_REUSEADDR-based fallback with different behavior) and adds a Security Considerations section describing multi-listener risks and operational hardening guidance.

Changes

Cohort / File(s)	Summary
Prefork docs `docs/api/fiber.md`, `docs/extra/internal.md`	Clarifies OS-specific prefork socket-binding behavior (Linux: `SO_REUSEPORT`; Windows: `SO_REUSEADDR`-based fallback with non-equivalent semantics). Splits binding workflow by OS and adds a "Security Considerations" section describing relaxed single-owner assumptions, multi-tenant/shared-host risks, trust-boundary expectations, and hardening steps (restrict trust boundary, dedicated service account, container/VM isolation, or disable prefork).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Suggested reviewers

sixcolors
efectn
ReneWerner87

Poem

🐰 I hopped through docs with careful care,

Prefork paths and sockets laid bare.
Linux hums with reuseport’s art,
Windows plays a different part.
Guard your ports — keep the ownership fair.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main documentation update about prefork security model and OS-specific socket behavior, which aligns with the changeset.
Description check	✅ Passed	The description covers motivation, detailed changes to both documentation files, and comprehensive testing results, but does not formally check the required template sections or checklist items.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch update-documentation-for-prefork-security-and-usage

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

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

gemini-code-assist

Code Review

This pull request updates the documentation for Fiber's preforking mechanism, clarifying the differences between Linux's SO_REUSEPORT and Windows' SO_REUSEADDR fallback. It also introduces a new 'Security Considerations' section providing hardening guidance for multi-listener setups. The review feedback suggests more precise technical descriptions for the Windows implementation, identifying the specific internal package used for Linux, and refining terminology regarding cross-platform behavioral differences.

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Copilot

Pull request overview

This PR updates Fiber’s prefork documentation to better explain OS-dependent socket semantics (Linux vs Windows) and to add explicit security/threat-model guidance for operators deploying prefork in shared environments.

Changes:

Clarified Linux SO_REUSEPORT vs Windows SO_REUSEADDR fallback behavior and noted semantic differences.
Added a new “Security Considerations” section describing multi-listener risks and hardening recommendations.
Mirrored the same OS distinction and operator guidance in the public API docs under the Prefork section.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
docs/extra/internal.md	Adds OS-specific prefork binding notes and a new security considerations subsection.
docs/api/fiber.md	Expands the Prefork docs with OS distinctions and hardening guidance for operators.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

gaby · 2026-04-26T22:24:52Z

@ReneWerner87 Ready to merge.

coderabbitai

Caution

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

⚠️ Outside diff range comments (1)

docs/extra/internal.md (1)
268-334: ⚠️ Potential issue | 🟡 Minor

Please run Markdown lint for this docs change.

I don’t see evidence that make markdown was run for the modified .md file; please run it and share the result in the PR checks.

As per coding guidelines **/*.md: Run make markdown to lint all Markdown files when modifying code.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/extra/internal.md` around lines 268 - 334, The Markdown file
docs/extra/internal.md was changed but the repo's Markdown linter wasn't run;
run the repository make target for Markdown linting (make markdown) to
produce/fix any formatting issues for the `**/*.md` rule, commit the resulting
fixes (or include the lint output) and push/update the PR so the CI/PR checks
show the make markdown result; ensure the PR contains either the updated
markdown from the linter or the lint log output.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Outside diff comments:
In `@docs/extra/internal.md`:
- Around line 268-334: The Markdown file docs/extra/internal.md was changed but
the repo's Markdown linter wasn't run; run the repository make target for
Markdown linting (make markdown) to produce/fix any formatting issues for the
`**/*.md` rule, commit the resulting fixes (or include the lint output) and
push/update the PR so the CI/PR checks show the make markdown result; ensure the
PR contains either the updated markdown from the linter or the lint log output.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 113de993-287c-4dc5-878d-8d3fb6fbffc1

📥 Commits

Reviewing files that changed from the base of the PR and between 54450c6 and 2d9b63c.

📒 Files selected for processing (1)

docs/extra/internal.md

📒 docs: expand prefork security and platform behavior guidance

dd1df86

gaby added the codex label Apr 26, 2026 — with ChatGPT Codex Connector

ReneWerner87 added v3 📒 Documentation labels Apr 26, 2026

ReneWerner87 added this to v3 Apr 26, 2026

ReneWerner87 added this to the v3 milestone Apr 26, 2026

gemini-code-assist Bot reviewed Apr 26, 2026

View reviewed changes

Comment thread docs/api/fiber.md Outdated

Comment thread docs/extra/internal.md

Comment thread docs/extra/internal.md Outdated

ReneWerner87 approved these changes Apr 26, 2026

View reviewed changes

gaby and others added 2 commits April 26, 2026 14:45

Update docs/extra/internal.md

f1c9886

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Update docs/api/fiber.md

54450c6

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

gaby marked this pull request as ready for review April 26, 2026 22:18

gaby requested a review from a team as a code owner April 26, 2026 22:18

gaby requested review from Copilot, efectn and sixcolors April 26, 2026 22:18

Copilot started reviewing on behalf of gaby April 26, 2026 22:19 View session

Copilot AI reviewed Apr 26, 2026

View reviewed changes

Comment thread docs/api/fiber.md Outdated

Comment thread docs/api/fiber.md Outdated

Comment thread docs/extra/internal.md Outdated

Comment thread docs/extra/internal.md

gaby and others added 2 commits April 26, 2026 18:23

Update docs/extra/internal.md

2d9b63c

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Apply suggestions from code review

c772a44

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

coderabbitai Bot reviewed Apr 26, 2026

View reviewed changes

ReneWerner87 merged commit 475c48b into main Apr 26, 2026
6 checks passed

ReneWerner87 deleted the update-documentation-for-prefork-security-and-usage branch April 26, 2026 22:42

github-project-automation Bot moved this to Done in v3 Apr 26, 2026

ReneWerner87 modified the milestones: v3, v3.3.0 May 22, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

📒 docs: clarify prefork security model and OS-specific socket behavior#4240

📒 docs: clarify prefork security model and OS-specific socket behavior#4240
ReneWerner87 merged 5 commits into
mainfrom
update-documentation-for-prefork-security-and-usage

gaby commented Apr 26, 2026

Uh oh!

coderabbitai Bot commented Apr 26, 2026 •

edited

Loading

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gaby commented Apr 26, 2026

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

gaby commented Apr 26, 2026

Motivation

Description

Testing

Uh oh!

coderabbitai Bot commented Apr 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Suggested reviewers

Poem

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gaby commented Apr 26, 2026

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

coderabbitai Bot commented Apr 26, 2026 •

edited

Loading