feat(compat): detect forge flavor (Gitea vs Forgejo/Codeberg) — endpoints and capabilities diverge #48

New issue

Closed

opened 2026-07-13 21:06:54 +00:00 by hexajon · 0 comments

hexajon commented

2026-07-13 21:06:54 +00:00

(Migrated from codeberg.org)

madtea treats every forge as "API v1, Gitea-compatible", but the flavors have genuinely diverged and madtea currently finds out via raw 404s and silent behavior differences.

Live evidence (2026-07-13, against codeberg.org):

madt_files action=get_ext → API error 404: 404 page not found — the extended-contents endpoint appears Gitea-only; plain action=get works.
action=contents (bulk read) is already documented Gitea-only in the tool description.
The label-filter divergence documented on #12: Forgejo's per-repo list labels= filter resolves org-label names; Gitea silently discards them (fail-open).
Gitea's 405 "Please try again later" transient (see #13) — flavor/version-specific server behavior.

Ask:

Flavor + version detection per host: one probe (e.g. /api/v1/version, plus the Forgejo-specific response headers where present), cached next to the host-keyed credentials so it's resolved once per forge, not per call.
Capability gating: flavor-aware paths choose the right endpoint (or degrade) instead of 404ing — e.g. get_ext/contents fall back to plain contents reads on Forgejo; label-name filters pass IDs on Gitea.
Actionable errors: when an action genuinely isn't available on the target flavor, say so — "not supported on Forgejo/Codeberg (Gitea-only endpoint)" — never a bare upstream 404.
docs/COMPAT.md: grow the matrix with a flavor column fed by the detection logic, so divergences are recorded once and tested (TestComparisonCoverageSummary-style guard if practical).

Acceptance:

A wrong-flavor call returns the actionable message, not 404 page not found.
Flavor detection is one cached probe per host; hermetic tests fake both flavors.
COMPAT.md documents every known divergence with its gating behavior.

madtea treats every forge as "API v1, Gitea-compatible", but the flavors have genuinely diverged and madtea currently finds out via raw 404s and silent behavior differences. Live evidence (2026-07-13, against codeberg.org): - `madt_files action=get_ext` → `API error 404: 404 page not found` — the extended-contents endpoint appears Gitea-only; plain `action=get` works. - `action=contents` (bulk read) is already documented Gitea-only in the tool description. - The label-filter divergence documented on #12: Forgejo's per-repo list `labels=` filter resolves org-label names; Gitea silently discards them (fail-open). - Gitea's 405 "Please try again later" transient (see #13) — flavor/version-specific server behavior. Ask: 1. **Flavor + version detection per host**: one probe (e.g. `/api/v1/version`, plus the Forgejo-specific response headers where present), cached next to the host-keyed credentials so it's resolved once per forge, not per call. 2. **Capability gating**: flavor-aware paths choose the right endpoint (or degrade) instead of 404ing — e.g. get_ext/contents fall back to plain contents reads on Forgejo; label-name filters pass IDs on Gitea. 3. **Actionable errors**: when an action genuinely isn't available on the target flavor, say so — "not supported on Forgejo/Codeberg (Gitea-only endpoint)" — never a bare upstream 404. 4. **docs/COMPAT.md**: grow the matrix with a flavor column fed by the detection logic, so divergences are recorded once and tested (`TestComparisonCoverageSummary`-style guard if practical). Acceptance: - A wrong-flavor call returns the actionable message, not `404 page not found`. - Flavor detection is one cached probe per host; hermetic tests fake both flavors. - COMPAT.md documents every known divergence with its gating behavior.

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

sixfold-space/madtea#48

No description provided.

Rows
Columns