Repository navigation
Closed
Description
Parent: #140
Tracked by: #134, #163, #164
Symbols (URL cluster sub-slice 2 — JS-value and static string helpers)
| Symbol | Home (packages/runtime/src/jsc/URL.zig @ 7ed99c02) |
Bun C++ (upstream/src/jsc/bindings/BunString.cpp) |
|---|---|---|
URL__fromJS |
:32 — (JSValue, *JSGlobalObject) ?*URL |
:596 — value.toWTFString (exception → null), empty/invalid → null, new WTF::URL |
URL__getHrefFromJS |
:46 |
:613 — coerce, empty/invalid → Dead, else url.string() |
URL__getHref |
:47 — (*String) String |
:630 — parse, invalid/empty → Dead |
URL__getHrefJoin |
:49 — (*String, *String) String |
:650 — WTF::URL(URL(base), relative), invalid → Dead |
URL__getFileURLString |
:48 |
:564 — URL::fileURLWithFileSystemPath(path).stringWithoutFragmentIdentifier() |
URL__pathFromFileURL |
:50 |
:640 — parse, invalid → Dead, else url.fileSystemPath() (percent-decoded path) |
Builds directly on #308's native parsed-URL record and the allocator-first WHATWG parse layer. Remaining URL-cluster symbols after this slice: BunString__toURL/toJSDOMURL + DOMURL__* (JS DOMURL object creation) and URL__originLength (Home declares it un-wrapped).
Acceptance criteria
-
URL__fromJScoerces any same-VM JSValue through ToString; a throwing coercion publishes the pending exception and returns null (Bun'sRETURN_IF_EXCEPTION → nullptr); empty/invalid → null without an exception; success returns the Private ABI: URL native record and component getters (fromString/deinit/href/protocol/username/password/search/host/hostname/port/pathname/hash/fragmentIdentifier) #308 native record. -
URL__getHrefFromJS/URL__getHrefreturn the full serialization as an owned BunString, Dead for empty/invalid input; coercion exceptions publish and return Dead. -
URL__getHrefJoinresolves the relative BunString against the parsed base throughurlParse(rel, base)and returns the joined serialization, Dead when either side is invalid. -
URL__getFileURLStringpercent-encodes each/-separated path segment with the WHATWG path encode set (slashes preserved, dot segments NOT resolved — WTF sets the path post-parse) and prefixesfile://. -
URL__pathFromFileURLreturns the percent-decoded path (%XXonly,+stays literal — path, not query) of the parsed input, Dead when invalid. - Engine additions stay allocator-first and minimal:
urlPercentEncodemadepub, one newpub urlPercentDecodehelper; zero behavior change to existing callers. - Compiled runtime fixture covers: fromJS on string/object-with-toString/throwing-toString (exception published, null returned), getHref family roundtrips, join with relative/absolute/dot-segment references against file and http bases, file-URL encode of paths with spaces/non-ASCII, file-path decode of percent-encoded and
+-containing paths, null tolerance. Fixture symbol count 307 → 313. - Home inventory
310/431, Bun inventory303/421;bun-private-abi-audit+c-api-auditgreen; fullzig build testzero new failures (worktree baseline-vs-candidate against the same pinned base).
Design constraints
- Same-VM coercion only: a foreign-VM EncodedValue returns null/Dead with a published TypeError, matching the established private-export VM-affinity rules.
- No new parser machinery: join uses the existing base-resolution path; file-URL encode reuses the existing path encode set; decode adds only the
+-free percent loop.
Metadata
Metadata
Assignees
Labels
No labels
Activity
feat(abi): expose the URL JS-value and static string helpers (#309)
docs(abi): publish URL helper boundary evidence (#309)
chrisbbreuer commentedon Jul 19, 2026
Evidence — landed on main as runtime
5ca8373c+ docsbcf9b0fd.Implementation:
src/c_api.zig: the six exports.URL__fromString's record builder was extracted intoprivateUrlCreateFromWTF8(shared withURL__fromJS) plus aprivateUrlHrefWTF8serializer used by the href family — zero behavior change to Private ABI: URL native record and component getters (fromString/deinit/href/protocol/username/password/search/host/hostname/port/pathname/hash/fragmentIdentifier) #308 semantics.URL__fromJS/URL__getHrefFromJSrun the standard same-VM preamble (ctxForEvaluation+ GC/string-arena swap + active-interpreter push), coerce viatoStringV, publish a TypeError for foreign-VM values, and publish thrown coercions throughprivateSetPendingAbrupt; empty/invalid yields null/Dead with no exception. The static helpers are context-free BunString in/out:getHrefre-serializes with no base,getHrefJoinparses the base then resolves the relative reference through the existingurlParse(rel, base)path,getFileURLStringbuildsfile://+ per-segment WHATWG path-set encoding (slashes kept, dot segments unresolved),pathFromFileURLreturns the percent-decoded path with+left literal.src/interpreter.zig:urlPercentEncode/UrlEncSetmadepub; one newpub urlPercentDecode(the+-free percent loop mirroring the form decoder). Allocator-first; no behavior change for existing callers.Validation:
tests/abi/home_private_value_shims.zig307 → 313/313: fromJS/getHrefFromJS on a URL string with JSnew URLparity, object-with-toString coercion, throwing-toString (exception published + null/Dead, then cleared), empty/invalid without exception, foreign-VM TypeError, getHref roundtrips, join parity across relative/absolute-path/dot-segment references against http and file bases, file-URL encode for Latin-1 and UTF-16 inputs (space/non-ASCII →%20/%C3%A9/%E2%82%AC), dot-segment preservation, pathFromFileURL decode incl. literal+, null tolerance across all six.bun-private-abi-audit: implemented-private 303/421 (pending 118).c-api-audit: 319 private profile exports, 117/117 public complete.test-home-public-abi: 50/50.e9869bc4: baseline 1152 passed / 3 failed vs candidate 1152 passed / 3 failed — identical failure sets (the three known pre-existing: gc slab size, wasm.decode malformed, wasm.validate GC canonical recursive type identity). Zero new failures.Inventories refreshed: Home 310/431 implemented (121 pending), Bun 303/421 (118 pending). Docs boundary evidence published in
docs/abi/README.md.