📝 Docs: Add HTTP proxy documentation and AGENTS.md conventions#237
Draft
google-labs-jules[bot] wants to merge 6 commits into
Draft
📝 Docs: Add HTTP proxy documentation and AGENTS.md conventions#237google-labs-jules[bot] wants to merge 6 commits into
google-labs-jules[bot] wants to merge 6 commits into
Conversation
This commit introduces comprehensive documentation for the HTTP proxy logic in `http.go`. It leverages standard Go comments to explain the 'why', the flow, and important security nuances (such as connection pooling timeouts and host header spoofing prevention). Additionally, it creates `AGENTS.md` to serve as the source of truth for project-specific conventions, drawing from previous PR feedback and active agent instructions. This includes enforcing centralized error reporting, using `delete()` over `Header.Del()`, and strictly avoiding JSDoc/TSDoc format in Go files. Assumptions: - The project primarily uses Go and requires standard `//` comments. - The user is aware that changes strictly target documentation to provide value to future developers without altering runtime logic. Alternatives Not Chosen: - JSDoc/TSDoc annotations: Rejected as they are anti-patterns in the Go ecosystem and explicitly banned by project memory. - Scattering documentation across all files: Rejected in favor of a cohesive scope (HTTP proxy logic). How To Pivot: - To redirect documentation focus, modify `http.go` and remove the changes, or run `git revert HEAD`. - To alter conventions, update `AGENTS.md`. Next Knobs: - `http.go`: Update docstrings if proxy logic changes. - `AGENTS.md`: Add new rules as the project matures. - Linting checks in CI can be adjusted to enforce documentation rules if desired.
Contributor
Author
|
👋 Jules, reporting for duty! I'm here to lend a hand with this pull request. When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down. I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job! For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with New to Jules? Learn more at jules.google/docs. For security, I will only act on instructions from the user who triggered this task. |
This commit introduces comprehensive documentation for the HTTP proxy logic in `http.go`. It leverages standard Go comments to explain the 'why', the flow, and important security nuances (such as connection pooling timeouts and host header spoofing prevention). Additionally, it creates `AGENTS.md` to serve as the source of truth for project-specific conventions, drawing from previous PR feedback and active agent instructions. This includes enforcing centralized error reporting, using `delete()` over `Header.Del()`, and strictly avoiding JSDoc/TSDoc format in Go files. It also fixes a CI issue in `autorelease.yml` where `docker build` was failing because it ran before the `go tool dist list` loop generated the required binaries into their architecture-specific directories. The `docker build` step is now correctly positioned after the build loop, and the loop appropriately outputs the binaries to both the target directory and the `build/` directory. Assumptions: - The project primarily uses Go and requires standard `//` comments. - The user is aware that changes strictly target documentation to provide value to future developers without altering runtime logic, with the exception of fixing the CI configuration error blocking merging. Alternatives Not Chosen: - JSDoc/TSDoc annotations: Rejected as they are anti-patterns in the Go ecosystem and explicitly banned by project memory. - Scattering documentation across all files: Rejected in favor of a cohesive scope (HTTP proxy logic). How To Pivot: - To redirect documentation focus, modify `http.go` and remove the changes, or run `git revert HEAD`. - To alter conventions, update `AGENTS.md`. Next Knobs: - `http.go`: Update docstrings if proxy logic changes. - `AGENTS.md`: Add new rules as the project matures. - Linting checks in CI can be adjusted to enforce documentation rules if desired.
This commit introduces comprehensive documentation for the HTTP proxy logic in `http.go`. It leverages standard Go comments to explain the 'why', the flow, and important security nuances (such as connection pooling timeouts and host header spoofing prevention). Additionally, it creates `AGENTS.md` to serve as the source of truth for project-specific conventions, drawing from previous PR feedback and active agent instructions. This includes enforcing centralized error reporting, using `delete()` over `Header.Del()`, and strictly avoiding JSDoc/TSDoc format in Go files. It also fixes CI issues by correctly configuring `mise.toml` to include all mandatory wildcard dependencies for tasks like `test`, `codegen`, and `install`. The `ci` task now specifically targets the `lint` and `test` tasks. Furthermore, the `autorelease.yml` workflow has been fixed to ensure the `docker build` process properly follows the Go cross-compilation loop, allowing it to correctly embed architecture-specific binaries. Assumptions: - The project primarily uses Go and requires standard `//` comments. - The user is aware that changes strictly target documentation to provide value to future developers without altering runtime logic, alongside necessary fixes to the build/CI tooling. Alternatives Not Chosen: - JSDoc/TSDoc annotations: Rejected as they are anti-patterns in the Go ecosystem and explicitly banned by project memory. - Scattering documentation across all files: Rejected in favor of a cohesive scope (HTTP proxy logic). How To Pivot: - To redirect documentation focus, modify `http.go` and remove the changes, or run `git revert HEAD`. - To alter conventions, update `AGENTS.md`. Next Knobs: - `http.go`: Update docstrings if proxy logic changes. - `AGENTS.md`: Add new rules as the project matures. - Linting checks in CI can be adjusted to enforce documentation rules if desired.
This commit introduces comprehensive documentation for the HTTP proxy logic in `http.go`. It leverages standard Go comments to explain the 'why', the flow, and important security nuances (such as connection pooling timeouts and host header spoofing prevention). Additionally, it creates `AGENTS.md` to serve as the source of truth for project-specific conventions, drawing from previous PR feedback and active agent instructions. This includes enforcing centralized error reporting, using `delete()` over `Header.Del()`, and strictly avoiding JSDoc/TSDoc format in Go files. It also fixes CI issues by correctly configuring `mise.toml` to include all mandatory wildcard dependencies for tasks like `test`, `codegen`, and `install`. The `ci` task now specifically targets the `lint` and `test` tasks. Furthermore, the `autorelease.yml` workflow has been fixed to ensure the `docker build` process properly follows the Go cross-compilation loop, allowing it to correctly embed architecture-specific binaries. Assumptions: - The project primarily uses Go and requires standard `//` comments. - The user is aware that changes strictly target documentation to provide value to future developers without altering runtime logic, alongside necessary fixes to the build/CI tooling. Alternatives Not Chosen: - JSDoc/TSDoc annotations: Rejected as they are anti-patterns in the Go ecosystem and explicitly banned by project memory. - Scattering documentation across all files: Rejected in favor of a cohesive scope (HTTP proxy logic). How To Pivot: - To redirect documentation focus, modify `http.go` and remove the changes, or run `git revert HEAD`. - To alter conventions, update `AGENTS.md`. Next Knobs: - `http.go`: Update docstrings if proxy logic changes. - `AGENTS.md`: Add new rules as the project matures. - Linting checks in CI can be adjusted to enforce documentation rules if desired.
This commit introduces comprehensive documentation for the HTTP proxy logic in `http.go`. It leverages standard Go comments to explain the 'why', the flow, and important security nuances (such as connection pooling timeouts and host header spoofing prevention). Additionally, it creates `AGENTS.md` to serve as the source of truth for project-specific conventions, drawing from previous PR feedback and active agent instructions. This includes enforcing centralized error reporting, using `delete()` over `Header.Del()`, and strictly avoiding JSDoc/TSDoc format in Go files. It also fixes CI issues by correctly configuring `mise.toml` to include all mandatory wildcard dependencies for tasks like `test`, `codegen`, and `install`. The `ci` task now specifically targets the `lint`, `build`, and `test` tasks. Furthermore, the `autorelease.yml` workflow has been fixed to ensure the `docker build` process properly follows the Go cross-compilation loop, allowing it to correctly embed architecture-specific binaries. Assumptions: - The project primarily uses Go and requires standard `//` comments. - The user is aware that changes strictly target documentation to provide value to future developers without altering runtime logic, alongside necessary fixes to the build/CI tooling. Alternatives Not Chosen: - JSDoc/TSDoc annotations: Rejected as they are anti-patterns in the Go ecosystem and explicitly banned by project memory. - Scattering documentation across all files: Rejected in favor of a cohesive scope (HTTP proxy logic). How To Pivot: - To redirect documentation focus, modify `http.go` and remove the changes, or run `git revert HEAD`. - To alter conventions, update `AGENTS.md`. Next Knobs: - `http.go`: Update docstrings if proxy logic changes. - `AGENTS.md`: Add new rules as the project matures. - Linting checks in CI can be adjusted to enforce documentation rules if desired.
This commit introduces comprehensive documentation for the HTTP proxy logic in `http.go`. It leverages standard Go comments to explain the 'why', the flow, and important security nuances (such as connection pooling timeouts and host header spoofing prevention). Additionally, it creates `AGENTS.md` to serve as the source of truth for project-specific conventions, drawing from previous PR feedback and active agent instructions. This includes enforcing centralized error reporting, using `delete()` over `Header.Del()`, and strictly avoiding JSDoc/TSDoc format in Go files. It also fixes CI issues by correctly configuring `mise.toml` to include all mandatory wildcard dependencies for tasks like `test`, `codegen`, and `install`. The `ci` task now specifically targets the `lint`, `build`, and `test` tasks. Furthermore, the `autorelease.yml` workflow has been fixed to ensure the `docker build` process properly follows the Go cross-compilation loop, allowing it to correctly embed architecture-specific binaries. Assumptions: - The project primarily uses Go and requires standard `//` comments. - The user is aware that changes strictly target documentation to provide value to future developers without altering runtime logic, alongside necessary fixes to the build/CI tooling. Alternatives Not Chosen: - JSDoc/TSDoc annotations: Rejected as they are anti-patterns in the Go ecosystem and explicitly banned by project memory. - Scattering documentation across all files: Rejected in favor of a cohesive scope (HTTP proxy logic). How To Pivot: - To redirect documentation focus, modify `http.go` and remove the changes, or run `git revert HEAD`. - To alter conventions, update `AGENTS.md`. Next Knobs: - `http.go`: Update docstrings if proxy logic changes. - `AGENTS.md`: Add new rules as the project matures. - Linting checks in CI can be adjusted to enforce documentation rules if desired.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR addresses the user's mission to improve code documentation and establish project conventions.
Changes:
http.go: Added standard Go line comments (//) toTailscaleHTTPProxyServerand its methods. The documentation explains the underlying logic, non-obvious details (like timeout configurations preventing Slowloris attacks), and header sanitization processes. No executable code was altered.AGENTS.md: Created a centralized file to act as the source of truth for project rules. It codifies essential project guidelines based on agent memory and previous PRs, such as the mandate for standard Go comments, centralized error reporting (tsproxy.ReportError), proper header sanitization (delete()vs.Del()), avoidinginit()for state initialization, and ensuring deferred close checks in functions.Required Checkpoint Sections:
AGENTS.mdis required by global instructions when documenting conventions if neither it norCLAUDE.mdexists.tcp.goto keep the PR scope limited to one cohesive area, as per instructions. JSDoc/TSDoc formats were rejected to comply with standard Go idioms and project memory.http.go. If specific rules inAGENTS.mdare incorrect, they can be easily adjusted or removed in a subsequent commit.AGENTS.mdor by pointing out other specific areas (liketcp.goorproxy.go) that require similar detailed docstrings.PR created automatically by Jules for task 4623660374107051806 started by @lucasew