Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Generated servers cannot route a path parameter declared `allowReserved: true`

Aperta
  • Qualcosa non va?
#113 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
48/100
Tipo di issue
Bug
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
julia, openapi
Ambito
api, backend

Direzione di ricerca

Leggi ext/OpenAPIHTTPExt.jl, OpenAPI.server_source e i dati _SERVER_OPS utilizzati dal codice glue del server generato. Inizia con SERVER_ROUNDTRIP_DOCUMENT in test/servergen.jl ed esegui i test esistenti di generazione del server. Il lavoro è completato quando il client e il server generati fanno il round-trip di un valore di percorso allowReserved, mentre i parametri greedy non finali non supportati producono una diagnostica al momento della generazione.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Summary

Since the runtime honours allowReserved on path parameters, a generated
client sends a slash-delimited path value as multiple path segments. A
generated server built from the same document still registers the raw
template (/documents/{path}), and HTTP.Router matches {name} against
exactly one segment — so the request 404s before it ever reaches
_decode_path_parameter.

One document therefore produces a client and a server that cannot talk to each
other, and the failure is a silent 404 rather than a diagnostic.

Reproduction

Document (3.0 or 3.2 — see the version note below):

"/documents/{path}": {
  "get": {
    "operationId": "getDocument",
    "parameters": [{
      "name": "path", "in": "path", "required": true,
      "allowReserved": true,
      "schema": { "type": "string" }
    }],
    "responses": { "200": { "description": "ok",
      "content": { "text/plain": { "schema": { "type": "string" } } } } }
  }
}

Generate the server, register! it on an HTTP.Router, and dispatch both wire
forms of the value opa/examples/public servers:

/documents/opa%2Fexamples%2Fpublic%20servers  -> 200 got:opa/examples/public servers
/documents/opa/examples/public%20servers      -> 404 <empty>   <-- what the client now sends

Cause

ext/OpenAPIHTTPExt.jl registers the template verbatim:

HTTP.register!(router, entry.method, string(path_prefix, entry.path), handler)

HTTP.Handlers.gethandler splits the request target on / and matches
segment by segment, so {path} is inherently single-segment.

_decode_path_parameter is not at fault — given the full multi-segment raw
text it _percent_decodes to the correct value. Only the route shape is wrong.

Constraints on a fix

  • HTTP.jl's only multi-segment construct is **, and insert! hard-errors
    with "/** double wildcard must be last segment in path". A greedy route is
    therefore only possible when the allowReserved parameter is the final
    path segment. /documents/{path}/versions is unservable this way and should
    raise a generation-time diagnostic rather than emit a silently broken route.
  • ** is not parsed as a Variable, so it contributes nothing to
    HTTP.getparams. The generated handler has to slice the tail out of
    request.target itself.
  • OpenAPI.server_source is a public seam and the HTTP extension is only one
    consumer. The "this operation has a greedy tail parameter" fact belongs in
    _SERVER_OPS (e.g. a greedy_path_arg field) rather than inside
    GENERATED_HTTP_SERVER_GLUE, so other framework extensions do not each
    re-derive it.
  • Not confined to style: simple. label and matrix values span segments
    too (.a/b, ;path=a/b), so those branches of _decode_path_parameter are
    in scope for whatever routing fix lands.
  • allowReserved preserves existing percent-escapes (_escape("%2F"; allow_reserved = true) == "%2F"), so a value whose literal text contains
    %2F is indistinguishable from a separator on the wire. That ambiguity is
    inherent to the feature and should be documented, not worked around.

Tests

SERVER_ROUNDTRIP_DOCUMENT in test/servergen.jl has no allowReserved path
parameter, which is why nothing caught this. A round-trip case there — generated
client target in, generated server handler argument out — is the right place for
the regression test.

Version note

The bundled spec schemas disagree about whether allowReserved is even legal
on a path parameter:

Document version allowReserved on a path parameter
3.0 accepted (generic Parameter property; PathParameter does not forbid it)
3.1 rejected — scoped to styles-for-query under unevaluatedProperties: false; the document fails to load even with strict = false
3.2 accepted, explicitly (styles-for-path)

So this affects 3.0 and 3.2 documents only. The client-side caveat is already
documented in MIGRATION.md and docs/src/clients.md.

Lingua principale
Julia
Stelle
56
Fork
16
Merge medio
1g 51m
PR unite (30g)
12

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di JuliaComputing/OpenAPI.jl

Tutte le issue di JuliaComputing/OpenAPI.jl

Issue simili

Altre issue su Julia

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.