Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-browser-foundation

Source of release 0.6.1

0.6.1 / 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.