dymokomi/luce-browser-foundation
Source of release 0.6.0
0.6.0 / docs / regions / r05.md
# Region r05: LibURL (`web_url`) — what other regions need to know
The `web_url` module is LibURL, ported faithfully: URL, the basic URL parser, Host, Origin, Site,
the public suffix list and URLPattern. Each fragment's header names the C++ it came from, and
`docs/namemap.tsv` lists every name.
## Signature and type changes against the skeleton
### New dependency
- The package depends on **luce-regex**. Its ECMAScript dialect replaces LibRegex's
`regex::ECMAScriptRegex` (DESIGN.md §7.1); `ecma_script_regex.lucb` is the seam
(`regex_ecma_script_regex_compile` / `_exec` / `_test` / `_capture_slot`, `RegexMatchResult`,
`RegexEcmaScriptCompileFlags`).
### Types filled or fixed by hand
- `UrlData` (was opaque): the fields of `URL::URL::Data`.
- `UrlTraits`: the hash of the serialization, and `url_eq` for equality; its methods are `pub`.
- `RegexEcmaScriptRegex`: the luce-regex program and the capture slots of the last exec.
- `ComponentExecutionResult`: `success` and `captures: ak.Vector[ak.String?]`.
- `PatternParser.m_encoding_callback` is an `EncodingCallback = func(ak.String) -> ak.String!`.
The generated `ak.Function1[const ak.String*, ak.String]` could not fail, and every callback the
donor passes is a plain function.
- `pattern_full_wildcard_regexp_value` is a `str` constant (`".*"`); `sv(...)` gives the StringView.
### Renamed or added functions
- `Host::has<T>()` / `Host::get<T>()` are templates over the variant's alternatives. They become
one function per alternative:
- `host_has_i_pv4_address`, `host_has_i_pv6_address`, `host_has_string`;
- `host_get_i_pv4_address`, `host_get_i_pv6_address`, `host_get_string`.
- `host_eq(this, other)` is the defaulted `Host::operator==`: `ak.String` has no `==`.
- `url_empty() -> Url` stands for `URL()`. A `Url` is not zeroable (its data pointer), but a `Url`
in zeroed memory, such as a field of a new cell, reads as `URL()` and is safe to write.
- `origin_tuple(scheme, host, port, domain = none) -> Origin` is the tuple constructor as a value.
`OriginTraits` and `origin_traits_hash` are `AK::Traits<URL::Origin>`.
- `public_suffix_data_the()` returns `PublicSuffixData*`, not `PublicSuffixData*?`.
- `parser_state_name` returns `str`.
- `pattern_generate_a_pattern_string` takes a `const ak.Vector[Part]*`: every caller passes a
Vector where the C++ takes `ReadonlySpan<Part>`.
- `component_compile` and `pattern_parser_*` take an `EncodingCallback`.
- Internal-linkage C++ functions are private in the port.
### Errors
- `PatternErrorOr<T>` is `T!` failing with `pattern_error` (`ErrorCode.package(501)`). The
`ErrorInfo` is kept in a module slot: read it with `pattern_take_error_info()` right after the
failure. Literal messages are also the failure's message.
- `regex_compile_error` (`ErrorCode.package(502)`) carries the regex syntax error.
### ak stubs touched
- Aligned with the signatures r01/r02 committed:
- `vector_at` / `vector_at_const`, `vector_first` / `vector_last` (and `_const`),
`vector_unchecked_append_u`;
- `string_base_eq(this, other: const StringBase*)`;
- `string_view_find_u8` / `find_last_u8` / `find_any_of` returning `usize?`;
- `utf16_string_from_utf8_string(const String*)`;
- `utf8_code_point_iterator_sub(this, other: const Utf8CodePointIterator*)`.
- Added to stub_r01: `ordered_hash_map_set`, `ordered_hash_map_get_k_const` (`-> const V*?`) and
`ordered_hash_map_size`. These match r01's port.
## Deviations from the donor
- **Copy-on-write.** `URL` keeps `AK::CopyOnWrite<Data>`. Without reference counts sharing cannot be
seen, so every write (`url_data_mutable`) copies the data first. Copies of a URL therefore never
see each other's writes, as in C++.
- **Integer formats and parsing.** These are written locally (`support.lucb`), because the generic
ak stubs cannot compute on T:
- AK::Format's `{}`, `{:x}` and `%{:02X}`;
- `AK::parse_number<u32>`, `StringView::to_number<u16>` and `String::number`.
- **Binary search.** The public suffix search inlines `AK::binary_search` with its
`DefaultComparator`.
- **Debug output.** `dbgln_if(URL_PARSER_DEBUG / URL_PATTERN_DEBUG, ...)` is not ported: both
switches are 0 in the donor build.
- **Regex memory.** The compiled regex program lives in C memory and is never released (FIXME
until blob finalizers exist).
- **Public suffix table.** `generated_public_suffix_data.lucb` was converted from the donor
build's `PublicSuffixData.cpp`. r12 owns the Luce port of `generate_public_suffix_data.py`.
- **URL::equals.** The `this == &other` identity shortcut is dropped: `other` is a copy in the port.
## Tests
- `tests_code_points` (in the module) needs nothing from ak and runs now.
- `tests/web_url_tests` ports Tests/LibURL (TestURL, TestPublicSuffix, TestURLPattern,
TestURLPatternConstructorStringParser) and adds expectations printed by the reference build.
`test.sh` checks it and runs it once the ak, text_codec and web_unicode stubs are
gone.
## What the local integration merge needed (r01 + r02 + r06 + r05)
66/66 tests passed on a scratch merge of the four branches. It did not build or run as merged:
### r01 against r02
These are real conflicts for the coordinator.
- `ak/ORDER` conflicts: resolve by keeping both lists.
- `text_support.lucb` repeats `import memory`, which `module.lucb` already imports.
- `utf16_view_hash` calls r01's non-generic `string_hash(const u8*?, ...)` with a `const u16*`.
- The FlyString and Utf16FlyString tables (`fly_string_table_find_view`, `fly_string_table_find`,
and the `utf16_fly_string_create_fly_string_from_cache_*`, `_from_data`, `_from_utf16_string`
and `_construct_utf16_string` functions) pass predicate structs where r01's
`hash_table_find_u32_tt_unary_predicate` takes an `ak.Function1[const T*, bool]`. They also use
`none` where r01 returns a non-optional `HashTableIterator[T]`.
In the scratch merge these functions were replaced by traps; web_url does not reach them.
### Shims for things not ported yet
Scratch only, never committed:
- **ak (r01 part 4 or r02 part 2):**
- `ByteBuffer` has no storage fields yet, and every `byte_buffer_*` that StringBuilder calls is
a stub;
- `LexicalPath` construct / canonicalize;
- `IPv6Address(Array<u16, 8>)` and `IPv6Address::operator[]`;
- `fill_with_random`.
- **web_unicode (r07):**
- `idna_to_ascii`: a per-label punycode stand-in, needed by the `public_suffix` test's Arabic
hosts;
- `code_point_has_identifier_start_property` / `_continue_property`: an ASCII approximation, used
by URLPattern names.
- **Memory:** two TestURL cases build 50,000- and 500,000-character URLs and run under
`with memory.heap:`, because the test runner's fixed buffer is about 1 MB.
## Compiler issue
- `.donors/luce-browser-tools/compiler-issues/else_under_try_leaks.lucb`: after one legitimate error
(an `else` on a fallible call inside a `try`), the checker rejects every later valid
fallible `else` in the module with the same message. It was a diagnostics bug only, fixed in
Luce 0.8.13.