WIP: feat/distributed-scaling-core #178
No reviewers
Labels
No labels
Compat/Breaking
Kind/Bug
Kind/Documentation
Kind/Enhancement
Kind/Feature
Kind/OpenSpec
Kind/Security
Kind/Testing
Priority/Critical
Priority/High
Priority/Low
Priority/Medium
RFC - Request For Comments
Reviewed/Confirmed
Reviewed/Duplicate
Reviewed/Invalid
Reviewed/Won't Fix
Status/Abandoned
Status/Blocked
Status/Need More Info
hermes-attempted
hermes-needs-clarification
hermes-ready
hermes-review
hermes-wip
human-required
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
agentic-forges/forgejo-mcp!178
Loading…
Reference in a new issue
No description provided.
Delete branch "byteflavour/feat/distributed-scaling-core"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Scaling Forgejo-MCP: Transitioning to a Distributed, Multi-User Architecture
This PR introduces a design blueprint (ADR) for hardening the Forgejo-MCP architecture
to support high-concurrency, multi-tenant environments. As the service moves from a
single-user CLI tool toward a distributed remote service (SSE/HTTP), we must address
fundamental bottlenecks in transport logic and observability.
op1st Pipelines as Code is skipping this commit.
User byteflavour is not allowed to trigger CI via pull_request in this repo.
op1st Pipelines as Code is skipping this commit.
User byteflavour is not allowed to trigger CI via pull_request in this repo.
op1st Pipelines as Code/code-scans-vhgqv is running.
Starting Pipelinerun code-scans-vhgqv in namespace op1st-pipelines
You can monitor the execution using the op1st Pipelines as Code PipelineRun viewer or through the command line by
using the tkn CLI with the following command:
tkn pr logs -n op1st-pipelines code-scans-vhgqv -fop1st Pipelines as Code/on-pull-request-n2nlq is running.
Starting Pipelinerun on-pull-request-n2nlq in namespace op1st-pipelines
You can monitor the execution using the op1st Pipelines as Code PipelineRun viewer or through the command line by
using the tkn CLI with the following command:
tkn pr logs -n op1st-pipelines on-pull-request-n2nlq -fop1st Pipelines as Code/code-scans-vhgqv has successfully validated your commit.
Task Statuses:
fetch-source
gitleaks-version
gitleaks
op1st Pipelines as Code/on-pull-request-n2nlq has failed.
Task Statuses:
fetch-source
build-and-test
commit-title-check
Failure snippet:
task commit-title-check has the status "Failed":Wait; am i confusing the agentic pipe? :D
My ADR isn't following any schema or respects folder's which may managed in the agentic pipe for now. U could say it's hand crafted ;) This document isn't finished ...
so i will initiate the openspec based on this ADR ... at least this was the plan. Maybe i have chosen the wrong place for this human authored ADR?
op1st Pipelines as Code/on-pull-request-pmhjw is running.
Starting Pipelinerun on-pull-request-pmhjw in namespace op1st-pipelines
You can monitor the execution using the op1st Pipelines as Code PipelineRun viewer or through the command line by
using the tkn CLI with the following command:
tkn pr logs -n op1st-pipelines on-pull-request-pmhjw -fop1st Pipelines as Code/code-scans-gdgdg is running.
Starting Pipelinerun code-scans-gdgdg in namespace op1st-pipelines
You can monitor the execution using the op1st Pipelines as Code PipelineRun viewer or through the command line by
using the tkn CLI with the following command:
tkn pr logs -n op1st-pipelines code-scans-gdgdg -fop1st Pipelines as Code/code-scans-gdgdg has successfully validated your commit.
Task Statuses:
fetch-source
gitleaks-version
gitleaks
Hi @byteflavour — thanks for this, and sorry for the noise above (I deleted a comment that misread your ADR entirely).
Good instinct asking where this lives. Let's keep it as one consolidated ADR rather than splitting into five separate OpenSpec changes — the five sections are facets of a single architectural shift (singleton CLI → multi-tenant remote), so they belong together as one decision record.
docs/design/is the right home for the human-authored ADR; no need to force it through the OpenSpec folder schema at this stage. Once the ADR direction is agreed, individual sections can spin out into OpenSpec changes when they're ready to implement — the ADR is the parent, OpenSpec changes are the children.On sequencing, my read on effort differs a little from a first glance: §1 (connection pool) is the cheapest win — it's essentially
http.Transporttuning on the client singleton, low risk, immediate benefit. §2 (observability) is a solid mid-size piece. §3 (multi-layer auth) is the heaviest — OIDC-at-edge plus two-layer credential passing is security-sensitive and needs its own careful design pass, so I'd treat it as the long pole. §5 (statelessness) is largely already true for the stdio singleton and mostly matters once the SSE/HTTP transport is real.So: finish fleshing out the single ADR here, we align on it, then carve implementation slices out of it. Thanks again — this is a valuable direction. 🎉
op1st Pipelines as Code/on-pull-request-pmhjw has failed.
Task Statuses:
fetch-source
build-and-test
commit-title-check
Failure snippet:
task commit-title-check has the status "Failed":op1st Pipelines as Code/forgejo-mcp-code-scans-7jwx5 is running.
Starting Pipelinerun forgejo-mcp-code-scans-7jwx5 in namespace op1st-pipelines
You can monitor the execution using the op1st Pipelines as Code PipelineRun viewer or through the command line by
using the tkn CLI with the following command:
tkn pr logs -n op1st-pipelines forgejo-mcp-code-scans-7jwx5 -fop1st Pipelines as Code/forgejo-mcp-code-scans-7jwx5 has successfully validated your commit.
Task Statuses:
fetch-source
gitleaks-version
gitleaks
op1st Pipelines as Code/forgejo-mcp-code-scans-gz6n8 is running.
Starting Pipelinerun forgejo-mcp-code-scans-gz6n8 in namespace op1st-pipelines
You can monitor the execution using the op1st Pipelines as Code PipelineRun viewer or through the command line by
using the tkn CLI with the following command:
tkn pr logs -n op1st-pipelines forgejo-mcp-code-scans-gz6n8 -fop1st Pipelines as Code/forgejo-mcp-code-scans-gz6n8 has successfully validated your commit.
Task Statuses:
fetch-source
gitleaks-version
gitleaks
op1st Pipelines as Code/forgejo-mcp-code-scans-vhk6l is running.
Starting Pipelinerun forgejo-mcp-code-scans-vhk6l in namespace op1st-pipelines
You can monitor the execution using the op1st Pipelines as Code PipelineRun viewer or through the command line by
using the tkn CLI with the following command:
tkn pr logs -n op1st-pipelines forgejo-mcp-code-scans-vhk6l -fop1st Pipelines as Code/forgejo-mcp-code-scans-vhk6l has successfully validated your commit.
Task Statuses:
fetch-source
gitleaks-version
gitleaks
op1st Pipelines as Code/forgejo-mcp-code-scans-kgzjx is running.
Starting Pipelinerun forgejo-mcp-code-scans-kgzjx in namespace op1st-pipelines
You can monitor the execution using the op1st Pipelines as Code PipelineRun viewer or through the command line by
using the tkn CLI with the following command:
tkn pr logs -n op1st-pipelines forgejo-mcp-code-scans-kgzjx -fop1st Pipelines as Code/forgejo-mcp-code-scans-kgzjx has successfully validated your commit.
Task Statuses:
fetch-source
gitleaks-version
gitleaks
This is a Living ADR. We are seeking architectural feedback before implementation begins.
Comment https://codeberg.org/goern/forgejo-mcp/pulls/178#issuecomment-16255829 must find it's way into the following issue.
When the PR is approved we will open an issue asking the community for review.
Thanks for this — the instinct to document scaling invariants before they become load-bearing is right, and it matches house precedent (
docs/design/output-bounding.mddeclares an architectural rule ahead of its full retrofit). I ran an adversarial review grounded in the current code. The impulse is sound; several mechanism claims are inaccurate against the actual tree, and the ADR overlaps an open spec. Requesting changes + a split.Factual corrections (verified against code):
SSE/HTTP already ship (
operation/operation.go:163-206), each already extracting a per-request token to context. The Context section's "as we move toward… via SSE/HTTP" understates current state — the transports exist; what's missing is the operational layer. Please reframe.§1 "Default Go HTTP clients limit concurrent persistent connections to 2 per host" is incorrect.
DefaultTransport.MaxIdleConnsPerHost = 2caps idle keep-alive connections;MaxConnsPerHostdefaults to0(unlimited concurrent). The real effect is idle-pool starvation under bursty fan-out (surplus conns closed + re-dialed → handshake cost), not a concurrency ceiling. Please reword to the idle-pool framing.§1 won't pay off as written. Every authenticated request builds a fresh
forgejo.NewClient(pkg/forgejo/forgejo.go:43) → fresh transport → fresh empty pool, discarded per call. TuningMaxIdleConnsPerHoston a single-use transport is a no-op. The prerequisite — a shared/cached transport across requests — must be stated as step zero, or the optimization buys nothing.Security — must harden or cut:
§4 Discovery (
X-Forgejo-URL) SSRF model is insufficient. IP-range blocklisting at resolve time is bypassable via DNS rebinding, HTTP redirects (the raw client sets noCheckRedirect—pkg/forgejo/rawhttp.go:53), IPv4-mapped IPv6 (::ffff:169.254.169.254), and metadata endpoints. If Discovery stays, the control must resolve-then-pin the connected IP atDialContext(not validate the hostname), reject redirects to disallowed targets, and cover IPv6-mapped + cloud-metadata ranges. Pinned stays default; Discovery opt-in/off by default.§4 Discovery is also not buildable as a near-term item. The target URL is read from the process-global
flag.URLeverywhere (forgejo.go:43,91,rawhttp.go:70,88). Per-request token plumbing exists; per-request URL plumbing does not. That's a refactor on the scale of the auth work and isn't budgeted — please mark it future-scope.Overlap with in-flight work:
openspec/changes/stateless-http-auth/(still has open blocker tasks). PAT-direct is already implemented (operation.go:112). Please cite that change and defer to it — or, if this supersedes it, say so explicitly. Carve gateway OAuth2/OIDC + XFF-trust into its own ADR; it carries its own threat model and shouldn't ride a scaling ADR.Smaller fixes:
§5
/readyz503-on-saturation is backpressure/load-shedding, not scaling — and coupling it to readiness risks a k8s endpoint-removal cascade (saturated pods drop out → load shifts → cascade). Reword: 503 = backpressure; horizontal scaling is the orchestrator's job, optionally driven by the §2 telemetry.§6 statelessness vs. connection pool reads as a contradiction. Clarify that "stateless" = no cross-request session state; process-level resource caches (the pool) are permitted by Factor VI.
§6 "Flags → Env → YAML" — current model is Flags → Env only (
cmd/cmd.go:105-191); no YAML loader exists. Mark YAML aspirational or move to Open Questions.Disposition: split into focused ADRs (transport/pooling · observability · SSRF/target-policy · health+config), each citing
stateless-http-auth. Hold §1 and §4-Discovery until the false premise and SSRF model are reworked. The core thesis is worth keeping — it just needs precise mechanisms and the right altitude.@byteflavour and maybe we should reframe this as a 'roadmap' as we show off the path forward rather than documenting actual architectural decisions. wdyt?
@goern wrote in https://codeberg.org/goern/forgejo-mcp/pulls/178#issuecomment-16302542:
Yes @goern, we can do this ... shall the reframing only be reflected in the wording or what are your thoughts? My next steps would be: Split the ADR, revise it, reframe it but keep it in the folder?!
@goern wrote in https://codeberg.org/goern/forgejo-mcp/pulls/178#issuecomment-16302506:
i am on it.
op1st Pipelines as Code/forgejo-mcp-code-scans-2gflh is running.
Starting Pipelinerun forgejo-mcp-code-scans-2gflh in namespace op1st-pipelines
You can monitor the execution using the op1st Pipelines as Code PipelineRun viewer or through the command line by
using the tkn CLI with the following command:
tkn pr logs -n op1st-pipelines forgejo-mcp-code-scans-2gflh -fop1st Pipelines as Code/forgejo-mcp-code-scans-2gflh has successfully validated your commit.
Task Statuses:
fetch-source
gitleaks-version
gitleaks
View command line instructions
Checkout
From your project repository, check out a new branch and test the changes.Merge
Merge the changes and update on Forgejo.Warning: The "Autodetect manual merge" setting is not enabled for this repository, you will have to mark this pull request as manually merged afterwards.