internetarchive / internetarchive/query-shaper
url-params + opensearch: incompatible encoding and placeholder semantics
- Dominant language
- TypeScript
- Stars
- 1
- Forks
- 0
- PR merge metrics
- No merged PRs in 30d
Description
## Problem Statement
`format="url-params"` and `action="opensearch"` are individually correct but
incompatible when combined. `url-params` renders an Expression's fields via
`URLSearchParams`, which encodes spaces as `+` and leaves `=`/`&` unescaped
as structural delimiters (e.g. `title=climate+change&year=2020`). The
`opensearch` Action's `{searchTerms}` substitution always runs the
Suggestion's `text` through `encodeURIComponent`, which percent-encodes
those same structural `=`/`&` characters — turning a valid multi-parameter
query string into one opaque, unusable blob
(`title%3Dclimate%2Bchange%26year%3D2020`).
This isn't just an encoding mismatch to patch, though: OpenSearch's
`{searchTerms}` placeholder is inherently a *single-value* substitution
point per the OpenSearch spec itself, not a "splice in a whole pre-built
query string" mechanism. `url-params` (multi-param output) and `opensearch`
(single-term substitution into a fixed template) were never really
composable to begin with, independent of which encoding gets used.
## Solution
Not yet decided — needs its own design pass. Candidate directions to
evaluate:
- Detect and reject (or warn on) the `format="url-params"` +
`action="opensearch"` combination outright, documenting that `url-params`
is meant to pair with `action="output"`/`action="none"` instead, letting
the host construct the final URL/fetch call themselves from the raw
query-string text.
- Or: give `opensearch`'s template substitution a second placeholder
convention (e.g. one that splices a pre-built query string in verbatim,
distinct from `{searchTerms}`'s single-encoded-value semantics) so the
two Format/Action combination can compose correctly.
## Further Notes
Surfaced while grilling SQL Expression support — this is unrelated to that
work and deliberately deferred. See the conversation that produced this
ticket for the verified repro:
```
URLSearchParams: title=climate+change&year=2020
encodeURIComponent: title%3Dclimate%2Bchange%26year%3D2020
```
---
_Migrated from GitLab issue #5 (private git.archive.org instance)._
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by tracing the format="url-params" and action="opensearch" entry points and reproduce the incompatibility with the URLSearchParams and encodeURIComponent examples in the issue. Review the OpenSearch placeholder semantics and compare the candidate directions. Done means an agreed design, implemented behavior, and documentation or tests covering the incompatible combination.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, typescript
- Domain
- api, backend-api-design
- Issue type
- Bug
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100