@structured-world/structured-public-domains 0.0.25 → 0.0.26

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -8,7 +8,7 @@ Compact Public Suffix List (PSL) for Rust.
8
8
  [![docs.rs](https://docs.rs/structured-public-domains/badge.svg)](https://docs.rs/structured-public-domains)
9
9
  [![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
10
10
 
11
- - **Zero** runtime dependencies
11
+ - **`no_std` + `alloc`** — runs in a WASM sandbox or on bare metal
12
12
  - **~108KB** embedded data (compact binary trie)
13
13
  - **~2.4M lookups/sec** on a single core (~420 ns per lookup)
14
14
  - **O(depth * log k)** trie traversal with per-node binary search (typically 2-3 steps)
@@ -33,6 +33,17 @@ assert_eq!(registrable_domain("sub.example.com"), Some("example.com".to_string()
33
33
  assert!(is_known_suffix("example.com"));
34
34
  ```
35
35
 
36
+ ### Without `std`
37
+
38
+ The lookup path needs an allocator for the strings it returns and nothing else:
39
+ no `std`, and no pointer-width atomic, so parts without a compare-and-swap are
40
+ in scope too. CI checks `thumbv7em-none-eabihf` and `thumbv6m-none-eabi`,
41
+ because a host check cannot fail on a constraint the host does not have.
42
+
43
+ ```toml
44
+ structured-public-domains = { version = "0", default-features = false, features = ["alloc"] }
45
+ ```
46
+
36
47
  ## Usage (JavaScript / TypeScript)
37
48
 
38
49
  The same PSL trie ships as a native TypeScript npm package — no WebAssembly, no
@@ -116,7 +127,9 @@ Benchmarks on Apple M-series (criterion, `cargo bench`):
116
127
  | Private domain (`mysite.github.io`) | ~450 ns | ~2.2M/s |
117
128
  | Long chain (`very.deep...co.uk`) | ~500 ns | ~2.0M/s |
118
129
 
119
- **Runtime memory:** The PSL trie is parsed lazily on first call (`OnceLock`), then cached for the lifetime of the process. Runtime footprint is ~530 KB (sorted `Vec` children with binary search lookup). The ~108KB binary blob is embedded in the binary at compile time.
130
+ **Runtime memory: nothing at rest.** The trie is searched in place, straight out of the embedded image, so there is nothing to parse, no structure to keep, no lazy initialization and nothing to synchronize on the first call. `include_bytes!` puts the ~108KB image in read-only data, which the loader maps on a hosted target and the linker places in flash on a bare-metal one; a lookup walks it where it lies.
131
+
132
+ A lookup itself does allocate, and an allocator-constrained caller should size for it: a `Vec` of the input's labels, a reusable buffer for the lowercased label being matched, and the returned suffix and registrable domain. Peak is a few hundred bytes for an ordinary domain, all released when the result is dropped.
120
133
 
121
134
  ## Why not `psl`?
122
135
 
@@ -125,11 +138,11 @@ Benchmarks on Apple M-series (criterion, `cargo bench`):
125
138
  | Embedded data | ~876KB (codegen match tree) | **108KB** (compact binary trie) |
126
139
  | Source size | 2.4MB codegen | 300 lines + 108KB blob |
127
140
  | Runtime deps | None | **None** |
128
- | Runtime memory | N/A (static) | **~530KB** |
141
+ | Runtime memory | N/A (static) | **None at rest** (searched in place) |
129
142
  | Lookup | O(depth) match tree | O(depth * log k) trie walk |
130
143
  | Auto-update | New crate version | Daily GitHub Actions check |
131
144
 
132
- Both crates have comparable lookup speed and zero runtime dependencies. `structured-public-domains` has ~8x smaller embedded data and auto-updates daily via GitHub Actions with domain-level changelogs.
145
+ Both crates have comparable lookup speed. `structured-public-domains` has ~8x smaller embedded data, allocates nothing at rest, builds without `std` or pointer-width atomics, and auto-updates daily via GitHub Actions with domain-level changelogs.
133
146
 
134
147
  ## Support the Project
135
148
 
@@ -0,0 +1,213 @@
1
+ // src/trie.ts
2
+ var utf8 = new TextDecoder("utf-8", { fatal: true });
3
+ var COUNT_ESCAPE = 31;
4
+ var INDEX_ENTRY = 3;
5
+ function parseTrie(data) {
6
+ return { image: data, at: 0 };
7
+ }
8
+ function headerOf(node) {
9
+ const byte = node.image[node.at];
10
+ if (byte === void 0) return void 0;
11
+ const packed = byte & COUNT_ESCAPE;
12
+ let children;
13
+ let body;
14
+ if (packed === COUNT_ESCAPE) {
15
+ const lo = node.image[node.at + 1];
16
+ const hi = node.image[node.at + 2];
17
+ if (lo === void 0 || hi === void 0) return void 0;
18
+ children = lo | hi << 8;
19
+ body = node.at + 3;
20
+ } else {
21
+ children = packed;
22
+ body = node.at + 1;
23
+ }
24
+ return {
25
+ suffixBoundary: (byte & 128) !== 0,
26
+ indexed: (byte & 64) !== 0,
27
+ wildcard: (byte & 32) !== 0,
28
+ children,
29
+ body
30
+ };
31
+ }
32
+ function varint(image, at) {
33
+ let value = 0;
34
+ let shift = 0;
35
+ for (let step = 0; step < 5; step++) {
36
+ const byte = image[at + step];
37
+ if (byte === void 0) return void 0;
38
+ value += (byte & 127) * 2 ** shift;
39
+ if ((byte & 128) === 0) return [value, at + step + 1];
40
+ shift += 7;
41
+ }
42
+ return void 0;
43
+ }
44
+ function entryAt(node, at, skippable) {
45
+ const len = node.image[at];
46
+ if (len === void 0) return void 0;
47
+ const labelEnd = at + 1 + len;
48
+ if (labelEnd > node.image.length) return void 0;
49
+ const label = decodeLabel(node.image, at + 1, labelEnd);
50
+ if (!skippable) {
51
+ return { label, child: { image: node.image, at: labelEnd }, next: labelEnd };
52
+ }
53
+ const read = varint(node.image, labelEnd);
54
+ if (read === void 0) return void 0;
55
+ const [subtreeLen, childAt] = read;
56
+ const next = childAt + subtreeLen;
57
+ if (next > node.image.length) return void 0;
58
+ return { label, child: { image: node.image, at: childAt }, next };
59
+ }
60
+ function indexEntry(node, header, i) {
61
+ const slot = header.body + i * INDEX_ENTRY;
62
+ const b0 = node.image[slot];
63
+ const b1 = node.image[slot + 1];
64
+ const b2 = node.image[slot + 2];
65
+ if (b0 === void 0 || b1 === void 0 || b2 === void 0) return void 0;
66
+ const at = node.at + (b0 | b1 << 8 | b2 << 16);
67
+ return at < node.image.length ? at : void 0;
68
+ }
69
+ function decodeLabel(data, start, end) {
70
+ for (let i = start; i < end; i++) {
71
+ if (data[i] >= 128) return utf8.decode(data.subarray(start, end));
72
+ }
73
+ let s = "";
74
+ for (let i = start; i < end; i++) s += String.fromCharCode(data[i]);
75
+ return s;
76
+ }
77
+ function childOf(node, label) {
78
+ const header = headerOf(node);
79
+ if (header === void 0) return void 0;
80
+ if (header.indexed) {
81
+ let lo = 0;
82
+ let hi = header.children;
83
+ while (lo < hi) {
84
+ const mid = lo + hi >>> 1;
85
+ const at2 = indexEntry(node, header, mid);
86
+ if (at2 === void 0) return void 0;
87
+ const entry = entryAt(node, at2, false);
88
+ if (entry === void 0) return void 0;
89
+ if (entry.label === label) return entry.child;
90
+ if (entry.label < label) lo = mid + 1;
91
+ else hi = mid;
92
+ }
93
+ return void 0;
94
+ }
95
+ let at = header.body;
96
+ for (let i = 0; i < header.children; i++) {
97
+ const entry = entryAt(node, at, true);
98
+ if (entry === void 0) return void 0;
99
+ if (entry.label === label) return entry.child;
100
+ if (entry.label > label) return void 0;
101
+ at = entry.next;
102
+ }
103
+ return void 0;
104
+ }
105
+ function hasChild(node, label) {
106
+ return childOf(node, label) !== void 0;
107
+ }
108
+ function hasWildcardChild(node) {
109
+ return headerOf(node)?.wildcard ?? false;
110
+ }
111
+ function isSuffixBoundary(node) {
112
+ return headerOf(node)?.suffixBoundary ?? false;
113
+ }
114
+ function validateTrie(data) {
115
+ const end = validateNode({ image: data, at: 0 });
116
+ if (end !== data.length) {
117
+ throw new Error("PSL data: trailing bytes after root node");
118
+ }
119
+ }
120
+ function validateNode(node) {
121
+ const header = headerOf(node);
122
+ if (header === void 0) {
123
+ throw new Error("PSL data: unexpected end of data");
124
+ }
125
+ let at = header.body;
126
+ if (header.indexed) at += header.children * INDEX_ENTRY;
127
+ let previous;
128
+ let sawWildcard = false;
129
+ for (let i = 0; i < header.children; i++) {
130
+ if (header.indexed) {
131
+ const slot = indexEntry(node, header, i);
132
+ if (slot === void 0) {
133
+ throw new Error("PSL data: index offset out of bounds");
134
+ }
135
+ if (slot !== at) {
136
+ throw new Error("PSL data: index offset does not point at its entry");
137
+ }
138
+ }
139
+ const len = node.image[at];
140
+ if (len === void 0) throw new Error("PSL data: unexpected end of data");
141
+ if (len === 0) throw new Error("PSL data: empty label");
142
+ const labelEnd = at + 1 + len;
143
+ if (labelEnd > node.image.length) {
144
+ throw new Error("PSL data: label runs past end of data");
145
+ }
146
+ const label = decodeLabel(node.image, at + 1, labelEnd);
147
+ if (previous !== void 0 && !(label > previous)) {
148
+ throw new Error("PSL data: children not strictly sorted");
149
+ }
150
+ previous = label;
151
+ if (label === "*") sawWildcard = true;
152
+ let childAt = labelEnd;
153
+ if (!header.indexed) {
154
+ const read = varint(node.image, labelEnd);
155
+ if (read === void 0) throw new Error("PSL data: malformed subtree length");
156
+ childAt = read[1];
157
+ }
158
+ const childEnd = validateNode({ image: node.image, at: childAt });
159
+ if (!header.indexed) {
160
+ const read = varint(node.image, labelEnd);
161
+ if (childEnd !== read[1] + read[0]) {
162
+ throw new Error("PSL data: subtree length disagrees with its contents");
163
+ }
164
+ }
165
+ at = childEnd;
166
+ }
167
+ if (header.wildcard !== sawWildcard) {
168
+ throw new Error("PSL data: wildcard flag disagrees with the children");
169
+ }
170
+ return at;
171
+ }
172
+ function lookupTrie(root, domain) {
173
+ const trimmed = domain.trim();
174
+ const stripped = trimmed.endsWith(".") ? trimmed.slice(0, -1) : trimmed;
175
+ if (stripped === "") return void 0;
176
+ const labels = stripped.split(".").reverse();
177
+ for (const label of labels) {
178
+ if (label === "" || label === "*" || label.startsWith("!")) return void 0;
179
+ }
180
+ let node = root;
181
+ let suffixDepth = 0;
182
+ let known = false;
183
+ for (let depth = 0; depth < labels.length; depth++) {
184
+ const label = labels[depth].toLowerCase();
185
+ if (hasWildcardChild(node)) {
186
+ if (hasChild(node, "!" + label)) {
187
+ suffixDepth = depth;
188
+ } else {
189
+ suffixDepth = depth + 1;
190
+ }
191
+ known = true;
192
+ }
193
+ const child = childOf(node, label);
194
+ if (child !== void 0) {
195
+ if (isSuffixBoundary(child)) {
196
+ suffixDepth = depth + 1;
197
+ known = true;
198
+ }
199
+ node = child;
200
+ continue;
201
+ }
202
+ break;
203
+ }
204
+ if (suffixDepth === 0) {
205
+ suffixDepth = 1;
206
+ known = false;
207
+ }
208
+ const suffix = labels.slice(0, suffixDepth).reverse().map((l) => l.toLowerCase()).join(".");
209
+ const registrableDomain = labels.length > suffixDepth ? `${labels[suffixDepth].toLowerCase()}.${suffix}` : void 0;
210
+ return { suffix, registrableDomain, known };
211
+ }
212
+
213
+ export { lookupTrie, parseTrie, validateTrie };
package/dist/index.cjs CHANGED
@@ -6,55 +6,71 @@ var pslData_cjs = require('./psl-data.cjs');
6
6
 
7
7
  // src/trie.ts
8
8
  var utf8 = new TextDecoder("utf-8", { fatal: true });
9
+ var COUNT_ESCAPE = 31;
10
+ var INDEX_ENTRY = 3;
9
11
  function parseTrie(data) {
10
- const cursor = { pos: 0 };
11
- const root = parseNode(data, cursor);
12
- if (cursor.pos !== data.length) {
13
- throw new Error("PSL data: trailing bytes after root node");
14
- }
15
- return root;
12
+ return { image: data, at: 0 };
16
13
  }
17
- function parseNode(data, cursor) {
18
- const flags = byteAt(data, cursor.pos++);
19
- if ((flags & -2) !== 0) {
20
- throw new Error("PSL data: reserved flag bits set");
21
- }
22
- const lo = byteAt(data, cursor.pos++);
23
- const hi = byteAt(data, cursor.pos++);
24
- let numChildren = lo | hi << 8;
25
- const MIN_CHILD_ENCODED_LEN = 5;
26
- const remaining = data.length - cursor.pos;
27
- if (remaining < 0 || numChildren > Math.floor(remaining / MIN_CHILD_ENCODED_LEN)) {
28
- throw new Error("PSL data: num_children exceeds remaining bytes");
14
+ function headerOf(node) {
15
+ const byte = node.image[node.at];
16
+ if (byte === void 0) return void 0;
17
+ const packed = byte & COUNT_ESCAPE;
18
+ let children;
19
+ let body;
20
+ if (packed === COUNT_ESCAPE) {
21
+ const lo = node.image[node.at + 1];
22
+ const hi = node.image[node.at + 2];
23
+ if (lo === void 0 || hi === void 0) return void 0;
24
+ children = lo | hi << 8;
25
+ body = node.at + 3;
26
+ } else {
27
+ children = packed;
28
+ body = node.at + 1;
29
29
  }
30
- const labels = [];
31
- const children = [];
32
- let prev;
33
- for (; numChildren > 0; numChildren--) {
34
- const labelLen = byteAt(data, cursor.pos++);
35
- if (labelLen === 0) {
36
- throw new Error("PSL data: empty label");
37
- }
38
- const labelEnd = cursor.pos + labelLen;
39
- if (labelEnd > data.length) {
40
- throw new Error("PSL data: label runs past end of data");
41
- }
42
- const label = decodeLabel(data, cursor.pos, labelEnd);
43
- cursor.pos = labelEnd;
44
- if (prev !== void 0 && !(label > prev)) {
45
- throw new Error("PSL data: children not strictly sorted");
46
- }
47
- prev = label;
48
- labels.push(label);
49
- children.push(parseNode(data, cursor));
30
+ return {
31
+ suffixBoundary: (byte & 128) !== 0,
32
+ indexed: (byte & 64) !== 0,
33
+ wildcard: (byte & 32) !== 0,
34
+ children,
35
+ body
36
+ };
37
+ }
38
+ function varint(image, at) {
39
+ let value = 0;
40
+ let shift = 0;
41
+ for (let step = 0; step < 5; step++) {
42
+ const byte = image[at + step];
43
+ if (byte === void 0) return void 0;
44
+ value += (byte & 127) * 2 ** shift;
45
+ if ((byte & 128) === 0) return [value, at + step + 1];
46
+ shift += 7;
50
47
  }
51
- return { suffixBoundary: (flags & 1) !== 0, labels, children };
48
+ return void 0;
52
49
  }
53
- function byteAt(data, i) {
54
- if (i >= data.length) {
55
- throw new Error("PSL data: unexpected end of data");
50
+ function entryAt(node, at, skippable) {
51
+ const len = node.image[at];
52
+ if (len === void 0) return void 0;
53
+ const labelEnd = at + 1 + len;
54
+ if (labelEnd > node.image.length) return void 0;
55
+ const label = decodeLabel(node.image, at + 1, labelEnd);
56
+ if (!skippable) {
57
+ return { label, child: { image: node.image, at: labelEnd }, next: labelEnd };
56
58
  }
57
- return data[i];
59
+ const read = varint(node.image, labelEnd);
60
+ if (read === void 0) return void 0;
61
+ const [subtreeLen, childAt] = read;
62
+ const next = childAt + subtreeLen;
63
+ if (next > node.image.length) return void 0;
64
+ return { label, child: { image: node.image, at: childAt }, next };
65
+ }
66
+ function indexEntry(node, header, i) {
67
+ const slot = header.body + i * INDEX_ENTRY;
68
+ const b0 = node.image[slot];
69
+ const b1 = node.image[slot + 1];
70
+ const b2 = node.image[slot + 2];
71
+ if (b0 === void 0 || b1 === void 0 || b2 === void 0) return void 0;
72
+ const at = node.at + (b0 | b1 << 8 | b2 << 16);
73
+ return at < node.image.length ? at : void 0;
58
74
  }
59
75
  function decodeLabel(data, start, end) {
60
76
  for (let i = start; i < end; i++) {
@@ -64,24 +80,42 @@ function decodeLabel(data, start, end) {
64
80
  for (let i = start; i < end; i++) s += String.fromCharCode(data[i]);
65
81
  return s;
66
82
  }
67
- function indexOfChild(node, label) {
68
- let lo = 0;
69
- let hi = node.labels.length - 1;
70
- while (lo <= hi) {
71
- const mid = lo + hi >>> 1;
72
- const cur = node.labels[mid];
73
- if (cur === label) return mid;
74
- if (cur < label) lo = mid + 1;
75
- else hi = mid - 1;
76
- }
77
- return -1;
78
- }
79
83
  function childOf(node, label) {
80
- const i = indexOfChild(node, label);
81
- return i < 0 ? void 0 : node.children[i];
84
+ const header = headerOf(node);
85
+ if (header === void 0) return void 0;
86
+ if (header.indexed) {
87
+ let lo = 0;
88
+ let hi = header.children;
89
+ while (lo < hi) {
90
+ const mid = lo + hi >>> 1;
91
+ const at2 = indexEntry(node, header, mid);
92
+ if (at2 === void 0) return void 0;
93
+ const entry = entryAt(node, at2, false);
94
+ if (entry === void 0) return void 0;
95
+ if (entry.label === label) return entry.child;
96
+ if (entry.label < label) lo = mid + 1;
97
+ else hi = mid;
98
+ }
99
+ return void 0;
100
+ }
101
+ let at = header.body;
102
+ for (let i = 0; i < header.children; i++) {
103
+ const entry = entryAt(node, at, true);
104
+ if (entry === void 0) return void 0;
105
+ if (entry.label === label) return entry.child;
106
+ if (entry.label > label) return void 0;
107
+ at = entry.next;
108
+ }
109
+ return void 0;
82
110
  }
83
111
  function hasChild(node, label) {
84
- return indexOfChild(node, label) >= 0;
112
+ return childOf(node, label) !== void 0;
113
+ }
114
+ function hasWildcardChild(node) {
115
+ return headerOf(node)?.wildcard ?? false;
116
+ }
117
+ function isSuffixBoundary(node) {
118
+ return headerOf(node)?.suffixBoundary ?? false;
85
119
  }
86
120
  function lookupTrie(root, domain) {
87
121
  const trimmed = domain.trim();
@@ -96,7 +130,7 @@ function lookupTrie(root, domain) {
96
130
  let known = false;
97
131
  for (let depth = 0; depth < labels.length; depth++) {
98
132
  const label = labels[depth].toLowerCase();
99
- if (hasChild(node, "*")) {
133
+ if (hasWildcardChild(node)) {
100
134
  if (hasChild(node, "!" + label)) {
101
135
  suffixDepth = depth;
102
136
  } else {
@@ -106,7 +140,7 @@ function lookupTrie(root, domain) {
106
140
  }
107
141
  const child = childOf(node, label);
108
142
  if (child !== void 0) {
109
- if (child.suffixBoundary) {
143
+ if (isSuffixBoundary(child)) {
110
144
  suffixDepth = depth + 1;
111
145
  known = true;
112
146
  }
package/dist/index.js CHANGED
@@ -1,4 +1,4 @@
1
- import { lookupTrie, parseTrie } from './chunk-EON4VJGA.js';
1
+ import { lookupTrie, parseTrie } from './chunk-ZK4NSAPK.js';
2
2
  import { PSL_BASE64 } from './psl-data.cjs';
3
3
 
4
4
  var cachedBytes;