Hacktoberfest 2026: as issues que os mantenedores marcaram para outubro, abertas e boas para iniciantes. Ver issues do Hacktoberfest

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

Aberta
  • Algo errado?
#113 0 comentários 0 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 1 dia

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
4/5
Tempo estimado
3-5 dias
Facilidade para iniciantes
48/100
Tipo de issue
Bug
Clareza
Razoavelmente clara
Status de atividade
Ativa
Stack de tecnologia
julia, openapi
Domínio
api, backend

Direção de pesquisa

Leia ext/OpenAPIHTTPExt.jl, OpenAPI.server_source e os dados _SERVER_OPS usados pelo código glue de servidor gerado. Comece com SERVER_ROUNDTRIP_DOCUMENT em test/servergen.jl e execute os testes existentes de geração de servidor. A tarefa estará concluída quando o cliente e o servidor gerados fizerem round-trip de um valor de caminho allowReserved, enquanto parâmetros greedy não finais não suportados produzirem um diagnóstico no momento da geração.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

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.

Linguagem predominante
Julia
Estrelas
56
Forks
16
Merge médio
1d 1h
PRs com merge (30d)
11

Preparar o ambiente

Este projeto não oferece contêiner de desenvolvimento, Dockerfile nem guia de contribuição, então a configuração fica por sua conta: comece pelo README e veja nosso guia da primeira contribuição para os passos gerais.

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de JuliaComputing/OpenAPI.jl

Todas as issues de JuliaComputing/OpenAPI.jl

Issues semelhantes

Mais issues de Julia

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.