Hacktoberfest 2026 : les issues que les mainteneurs ont marquées pour octobre, ouvertes et accessibles aux débutants. Parcourir les issues Hacktoberfest

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

Ouverte
  • Quelque chose ne va pas ?
#113 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Les mainteneurs répondent en général sous 1 jour

Personne n'a encore pris cette issue.

Évaluation

Difficulté
4/5
Temps estimé
3-5 jours
Accessibilité débutants
48/100
Type d'issue
Bug
Clarté
Plutôt claire
Activité
Active
Stack technique
julia, openapi
Domaine
api, backend

Piste de recherche

Lisez ext/OpenAPIHTTPExt.jl, OpenAPI.server_source et les données _SERVER_OPS utilisées par le code glue de serveur généré. Commencez par SERVER_ROUNDTRIP_DOCUMENT dans test/servergen.jl et exécutez ses tests existants de génération de serveur. C’est terminé lorsque le client et le serveur générés effectuent un round-trip avec une valeur de chemin allowReserved, tandis que les paramètres greedy non finaux non pris en charge produisent un diagnostic lors de la génération.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Description

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.

Langage dominant
Julia
Étoiles
56
Forks
16
Merge moyen
1 j 51 min
PR mergées (30 j)
12

Préparer son environnement

Ce projet ne fournit ni conteneur de développement, ni Dockerfile, ni guide de contribution : l'installation est à votre charge. Commencez par son README, et consultez notre guide de la première contribution pour les étapes générales.

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de JuliaComputing/OpenAPI.jl

Toutes les issues de JuliaComputing/OpenAPI.jl

Issues similaires

Plus d'issues Julia

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.