Skip to content

feat(client): escape_path_chars percent-encodes extra characters in path parameters - #122

Merged
tanmaykm merged 1 commit into
mainfrom
escape-path-chars
Sep 22, 2026
Merged

tanmaykm merged 1 commit into
mainfrom
escape-path-chars

Conversation

@tanmaykm

Copy link
Copy Markdown
Member

Fixes #120.

Adds a client-level option that percent-encodes additional characters in path parameter values, on top of the standard RFC 3986 escaping:

client = Example.Client("https://api.example.com"; escape_path_chars = ".")
Example.getcustomer("acme.example.com-42"; client)
# GET /customers/acme%2Eexample%2Ecom-42

Some routers cannot match a literal . in a dynamic segment (Rails reads it as a format suffix and 404s), but do match %2E because they route on the raw path. RFC 3986 §2.3 makes both spellings the same identifier, so servers that decode before routing are unaffected.

Behaviour

  • Default is empty, so existing clients send the same bytes as before.
  • Applies to the values of every path parameter of every operation: scalars, array items, and object keys and values, for simple, label, and matrix styles, and for content-typed path parameters unless the encoder produced a pre-encoded value.
  • Style delimiters (. for label, ;/= for matrix) and the parameter name from the path template are never touched.
  • Composes with allowReserved: reserved characters still pass through, listed characters are encoded (a/b.c -> a/b%2Ec).
  • % is rejected in escape_path_chars with an ArgumentError, since it would re-encode the percent-encoding itself.

Changes

  • src/runtime.jl: Client.escape_path_chars field and constructor keyword; _percent_encode_chars; escape_chars threaded through _path_scalar, _path_array, _path_object, _path_parameter, and both path branches of _append_parameter!.
  • test/runtime.jl: unit coverage for each style, delimiter preservation, allowReserved composition, and constructor validation.
  • test/runtime_integration.jl: live HTTP check of the wire target with and without the option, and combined with allowReserved.
  • docs/src/clients.md: new "Extra percent-encoding in path parameters" section.
  • MIGRATION.md: maps the 0.2 pre_request_hook workaround to the new option.

Tests

  • julia +1.12 --project=. -e 'using Pkg; Pkg.test()'
  • julia +1.10.11 --project=. -e 'using Pkg; Pkg.test()'

…ath parameters

Some routers (Rails in particular) end a dynamic path segment at a
literal `.` and treat the remainder as a format suffix, so a value such
as `acme.example.com-42` only routes when sent as
`acme%2Eexample%2Ecom-42`. RFC 3986 leaves `.` unreserved, so the
standard escaper never produces that spelling, and pre-encoded input is
double-encoded.

`Client(; escape_path_chars = ".")` names characters to percent-encode
in every path parameter value after the standard escaping. Style
delimiters and the template parameter name are left alone, and the
option composes with `allowReserved`. `%` is rejected. The default is
empty, so existing clients are unchanged.

Fixes #120
@tanmaykm
tanmaykm merged commit a694f06 into main Sep 22, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Client option to percent-encode additional characters (e.g. .) in path parameters

1 participant