tracker

38.8 KB

1. // hl:time plugin — native shared library (libtime.so, dlopen'd by the runtime)
2. //
3. // The clock (D22):
4. // hl_time_now() → epoch milliseconds, UTC wall clock (Number)
5. // hl_time_timestamp(ms?) → ISO-8601 UTC "YYYY-MM-DDTHH:MM:SS.mmmZ" (String)
6. // hl_time_monotonic() → nanoseconds off a monotonic counter (Number)
7. //
8. // …and TIME AS AN EVENT SOURCE (mission 254):
9. // hl_time_timer(secs, repeat) → { id, events } — `events` is a LOOP SOURCE
10. // whose wake fd IS a timerfd, so the interpreter
11. // loop's epoll (mission 256) blocks on the
12. // kernel timer itself instead of polling
13. // hl_time_timer_stop(id) → disarm, close, retire
14. // hl_time_sleep(secs) → BLOCKING nanosleep (the creator's ruling: a
15. // basic tool for tests and debugging)
16. //
17. // …and TIME ZONES (ticket #5), over the system's TZif files — see the last
18. // section: hl_time_offset / _local / _fromLocal / _localTimestamp / _isZone.
19. //
20. // The clock calls allocate nothing and hold no state; `timestamp` renders into a
21. // module-level buffer: the runtime dupes returned strings into its own tracker
22. // the instant the call returns (plugin_loader.zig hlToValue .hl_string) and a
23. // plugin call never yields, so the buffer cannot be observed stale or torn.
24. //
25. // Number is f64. Epoch ms (~1.8e12) is exact well past the year 200000, and
26. // monotonic ns stays exact for the first ~104 days of counter uptime (2^53 ns);
27. // beyond that the granularity coarsens above 1 ns, which is irrelevant for the
28. // difference-measurement the call exists for.
30. const std = @import("std");
31. const linux = std.os.linux;
32. const api = @import("plugin_api");
33. const HlValue = api.HlValue;
34. const HlObject = api.HlObject;
35. const HlField = api.HlField;
36. const HlIterator = api.HlIterator;
37. const HlString = api.HlString;
39. var gpa = std.heap.DebugAllocator(.{ .stack_trace_frames = 0 }){};
40. const allocator = gpa.allocator();
42. fn hlStr(s: []const u8) HlString {
43. return .{ .ptr = s.ptr, .len = s.len };
44. }
46. fn nowMs() i64 {
47. var ts: linux.timespec = undefined;
48. _ = linux.clock_gettime(linux.CLOCK.REALTIME, &ts);
49. return @as(i64, ts.sec) * 1000 + @divTrunc(@as(i64, ts.nsec), 1_000_000);
50. }
52. export fn hl_time_now(_: u32, _: [*]const HlValue) callconv(.c) HlValue {
53. return api.makeNumber(@floatFromInt(nowMs()));
54. }
56. export fn hl_time_monotonic(_: u32, _: [*]const HlValue) callconv(.c) HlValue {
57. var ts: linux.timespec = undefined;
58. _ = linux.clock_gettime(linux.CLOCK.MONOTONIC, &ts);
59. const ns: i64 = @as(i64, ts.sec) * 1_000_000_000 + @as(i64, ts.nsec);
60. return api.makeNumber(@floatFromInt(ns));
61. }
63. // "YYYY-MM-DDTHH:MM:SS.mmmZ" is 24 bytes; the year field widens for absurd
64. // inputs, so give it room rather than truncating.
65. var iso_buf: [40]u8 = undefined;
67. export fn hl_time_timestamp(argc: u32, argv: [*]const HlValue) callconv(.c) HlValue {
68. // Argument is optional: absent, null, or non-numeric all mean "now". The
69. // .hl wrapper declares `timestamp(ms)`, so a no-arg call arrives as one
70. // hl_null — the same thing.
71. var ms: i64 = if (argc > 0 and argv[0].type == .hl_number)
72. @intFromFloat(argv[0].data.number)
73. else
74. nowMs();
76. // Pre-epoch instants: floor the division so the millisecond part stays in
77. // [0, 999] and the second walks backwards (std.time.epoch is u64-only).
78. var secs: i64 = @divFloor(ms, 1000);
79. var millis: i64 = ms - secs * 1000;
80. if (secs < 0) {
81. // Dates before 1970 have no u64 epoch representation; rather than
82. // render garbage, clamp to the epoch itself and say so via the value.
83. secs = 0;
84. millis = 0;
85. ms = 0;
86. }
88. const es = std.time.epoch.EpochSeconds{ .secs = @intCast(secs) };
89. const yd = es.getEpochDay().calculateYearDay();
90. const md = yd.calculateMonthDay();
91. const ds = es.getDaySeconds();
93. const out = std.fmt.bufPrint(&iso_buf, "{d:0>4}-{d:0>2}-{d:0>2}T{d:0>2}:{d:0>2}:{d:0>2}.{d:0>3}Z", .{
94. yd.year,
95. md.month.numeric(),
96. @as(u32, md.day_index) + 1,
97. ds.getHoursIntoDay(),
98. ds.getMinutesIntoHour(),
99. ds.getSecondsIntoMinute(),
100. @as(u32, @intCast(millis)),
101. }) catch return api.makeError("hl:time timestamp() could not format the instant");
103. return api.makeString(out);
104. }
106. // ═══════════════════════════════════════════════════════════════════════════
107. // TIME AS AN EVENT SOURCE (mission 254)
108. // ═══════════════════════════════════════════════════════════════════════════
109. //
110. // `every(n)` / `after(n)` / `until(t)` are ONE primitive: a timerfd registered
111. // with the interpreter's event loop as an ordinary source, exactly the shape
112. // `spawn()` hands back from hl:proc. Two properties are the whole reason it is a
113. // timerfd rather than a thread or a deadline the loop checks:
114. //
115. // THE WAKE FD IS THE TIMER ITSELF. Mission 256 taught the loop to block in one
116. // `epoll_wait` over its sources' `HlIterator.wake_fd`s. A timerfd IS such an
117. // fd, so a timer costs one kernel wakeup at the instant it is due — not a 1ms
118. // poll that could never resolve a 1ms interval in the first place. An idle
119. // process with no timers is untouched (`tools/idle-cpu-gate.sh`).
120. //
121. // THE KERNEL OWNS THE SCHEDULE, so `every` cannot drift. `timerfd_settime` is
122. // given an ABSOLUTE deadline on CLOCK_MONOTONIC plus an interval, and the
123. // kernel re-arms from the previous EXPIRY, never from when anyone read the fd.
124. // The handler's own runtime is therefore not added to the next round — which
125. // is exactly the defect a `sleep(interval)` loop has.
126. //
127. // WHY `tryNext` READS THE CLOCK AND NOT THE FD. `loop_wait.Waiter` DRAINS every
128. // fd it was woken by (`read(fd, &sink, 8)`) before the loop's poll round — that
129. // is the level-triggered race argument in loop_wait.zig's header, and it means
130. // the timerfd's expiration COUNT is already gone by the time this poll runs. So
131. // the count is not the signal; the deadline is. Both sides read the same
132. // CLOCK_MONOTONIC and the kernel expires at-or-after the absolute deadline it
133. // was handed, so `now >= deadline` is guaranteed true when the bell rings. A
134. // dropped or duplicated wake is harmless in both directions: a duplicate polls
135. // to `null`, and a missed one is picked up by the loop's 250ms safety timeout.
137. // RAW SYSCALLS, NO LIBC. This .so has never linked libc (`timestamp` renders
138. // with std.fmt and the clock reads go through `linux.clock_gettime`), and the
139. // timer half keeps it that way — `std.os.linux` has timerfd and nanosleep, so
140. // nothing here needs `build.zig` to gain a `link_libc` it did not have.
141. fn timerfdCreate() i32 {
142. const rc = linux.timerfd_create(.MONOTONIC, .{ .NONBLOCK = true, .CLOEXEC = true });
143. const fd: isize = @bitCast(rc);
144. return if (fd < 0) -1 else @intCast(fd);
145. }
147. fn timerfdSetAbs(fd: i32, spec: *const linux.itimerspec) bool {
148. const rc = linux.timerfd_settime(fd, .{ .ABSTIME = true }, spec, null);
149. return @as(isize, @bitCast(rc)) == 0;
150. }
152. fn timerfdDisarm(fd: i32) void {
153. const zero = linux.itimerspec{
154. .it_interval = .{ .sec = 0, .nsec = 0 },
155. .it_value = .{ .sec = 0, .nsec = 0 },
156. };
157. _ = linux.timerfd_settime(fd, .{}, &zero, null);
158. }
160. fn monoNs() i64 {
161. var ts: linux.timespec = undefined;
162. _ = linux.clock_gettime(linux.CLOCK.MONOTONIC, &ts);
163. return @as(i64, ts.sec) * 1_000_000_000 + @as(i64, ts.nsec);
164. }
166. /// THE FLOOR, and it is the SAME NUMBER IN BOTH REALMS (mission 254).
167. ///
168. /// The creator confirmed fractional seconds — "a millisecond is just 0.001 then
169. /// thats okay" — and server-side that is not the limit: a timerfd carries
170. /// nanoseconds and the loop blocks on it. THE BROWSER IS THE LIMIT, and it was
171. /// MEASURED rather than quoted (tests/browser/tests/66-timers.mjs prints the
172. /// number it measured on every run). HTML's timer nesting rule clamps a chained
173. /// `setTimeout(…, 0)` to 4ms from the fifth nesting level on, and a `setInterval`
174. /// asked for 1ms delivers ~4ms periods.
175. ///
176. /// So `every(0.001)` would mean two different things in the two realms, and the
177. /// SAME `on t.tick()` handler is meant to run in both. The brief's choice was
178. /// "document the divergence with the measured number, or clamp both realms to
179. /// the same honest minimum" — CLAMPED, because a silent target divergence is
180. /// already a named defect class in this tree and because a number the author
181. /// writes should mean one thing everywhere. Anything below the floor is raised
182. /// to it, in both realms (`server.js` carries the same constant), and
183. /// `plugins/time/server.hl` says so where an author will read it.
184. const FLOOR_NS: i64 = 4_000_000;
186. /// ONE ARMED TIMER. Never freed: the struct is ~48 bytes, it is referenced by an
187. /// iterator the runtime owns, and freeing it would need the loop's poll round and
188. /// the GC sweep to agree on an order they have no reason to. `stop()` closes the
189. /// fd (which is the only scarce resource) and marks it dead; the poll then answers
190. /// `null` forever, which is what a retired source must do.
191. const Timer = struct {
192. fd: i32 = -1,
193. /// 0 = ONE-SHOT. `after()` and `until()` are `every()` that fires once.
194. interval_ns: i64 = 0,
195. /// The next fire's ABSOLUTE CLOCK_MONOTONIC instant — the same value the
196. /// kernel holds, which is what makes `now >= deadline` exact rather than
197. /// approximate.
198. deadline_ns: i64 = 0,
199. count: f64 = 0,
200. stopped: bool = false,
201. };
203. /// id → Timer, 1-based; `0` is "no timer" so a default-initialised member is
204. /// never mistaken for one. Ids are never reused: `stop()` leaves the slot dead
205. /// rather than freeing it, so a stale id can only ever answer "already stopped".
206. var timers = std.ArrayListUnmanaged(*Timer).empty;
208. fn timerById(id: f64) ?*Timer {
209. if (id < 1) return null;
210. const idx: usize = @intFromFloat(id - 1);
211. if (idx >= timers.items.len) return null;
212. return timers.items[idx];
213. }
215. fn timerTryNext(ctx: ?*anyopaque) callconv(.c) HlValue {
216. const t: *Timer = @ptrCast(@alignCast(ctx orelse return api.makeNull()));
217. if (t.stopped) return api.makeNull();
218. const now = monoNs();
219. if (now < t.deadline_ns) return api.makeNull();
221. t.count += 1;
222. if (t.interval_ns == 0) {
223. // A ONE-SHOT IS SPENT. The .hl half retires the source and closes the fd
224. // (mission 249: a source that will never speak again must not keep the
225. // program alive); this flag makes the polls between here and there
226. // answer null rather than fire a second time.
227. t.stopped = true;
228. } else {
229. // SCHEDULED FROM THE ORIGIN, and CAUGHT UP BY SKIPPING. Advancing by one
230. // interval keeps the phase the first fire established, so the handler's
231. // own runtime never accumulates. If the loop was busy for longer than an
232. // interval the missed rounds are DROPPED rather than delivered as a
233. // burst — a periodic timer that owes you a backlog is a stampede, and
234. // the kernel's own timerfd overrun count is discarded for the same
235. // reason (see the header: the Waiter has already drained it).
236. t.deadline_ns += t.interval_ns;
237. while (t.deadline_ns <= now) t.deadline_ns += t.interval_ns;
238. }
240. const fields = allocator.alloc(HlField, 2) catch return api.makeNull();
241. fields[0] = .{ .key = hlStr("count"), .value = api.makeNumber(t.count) };
242. fields[1] = .{ .key = hlStr("at"), .value = api.makeNumber(@floatFromInt(nowMs())) };
243. const obj = allocator.create(HlObject) catch return api.makeNull();
244. obj.* = .{ .fields = fields.ptr, .field_count = 2, .deinit_fn = null };
245. return api.makeObject(obj);
246. }
248. fn timerDeinit(ctx: ?*anyopaque) callconv(.c) void {
249. const t: *Timer = @ptrCast(@alignCast(ctx orelse return));
250. t.stopped = true;
251. }
253. /// hl_time_timer(seconds, repeat) → { id, events }
254. export fn hl_time_timer(argc: u32, argv: [*]const HlValue) callconv(.c) HlValue {
255. if (argc < 1 or argv[0].type != .hl_number) {
256. return api.makeError("hl:time timer: pass the interval in SECONDS (fractions allowed)");
257. }
258. const secs = argv[0].data.number;
259. if (!(secs == secs) or secs < 0) { // NaN or negative
260. return api.makeError("hl:time timer: the interval must be a positive number of seconds");
261. }
262. const repeat = argc >= 2 and argv[1].type == .hl_bool and argv[1].data.boolean;
264. var ns: i64 = @intFromFloat(secs * 1_000_000_000.0);
265. if (ns < FLOOR_NS) ns = FLOOR_NS;
267. const fd = timerfdCreate();
268. if (fd < 0) return api.makeError("hl:time timer: timerfd_create failed");
270. const t = allocator.create(Timer) catch return api.makeError("hl:time: out of memory");
271. t.* = .{ .fd = fd, .interval_ns = if (repeat) ns else 0, .deadline_ns = monoNs() + ns };
273. // ABSOLUTE, so the kernel and this plugin hold the SAME instant — the whole
274. // exactness argument in the header. The interval is the kernel's own re-arm,
275. // which is what makes `every` drift-free rather than nearly drift-free.
276. const spec = linux.itimerspec{
277. .it_interval = .{
278. .sec = if (repeat) @intCast(@divTrunc(ns, 1_000_000_000)) else 0,
279. .nsec = if (repeat) @intCast(@mod(ns, 1_000_000_000)) else 0,
280. },
281. .it_value = .{
282. .sec = @intCast(@divTrunc(t.deadline_ns, 1_000_000_000)),
283. .nsec = @intCast(@mod(t.deadline_ns, 1_000_000_000)),
284. },
285. };
286. if (!timerfdSetAbs(fd, &spec)) {
287. _ = linux.close(fd);
288. return api.makeError("hl:time timer: timerfd_settime failed");
289. }
291. timers.append(allocator, t) catch return api.makeError("hl:time: out of memory");
292. const id: f64 = @floatFromInt(timers.items.len);
294. const iter = allocator.create(HlIterator) catch return api.makeError("hl:time: out of memory");
295. iter.* = .{
296. .context = @ptrCast(t),
297. .next_fn = &timerTryNext,
298. .deinit_fn = &timerDeinit,
299. .try_next_fn = &timerTryNext,
300. .wake_fd = fd,
301. };
303. const fields = allocator.alloc(HlField, 2) catch return api.makeNull();
304. fields[0] = .{ .key = hlStr("id"), .value = api.makeNumber(id) };
305. fields[1] = .{ .key = hlStr("events"), .value = api.makeIterator(iter) };
306. const obj = allocator.create(HlObject) catch return api.makeNull();
307. obj.* = .{ .fields = fields.ptr, .field_count = 2, .deinit_fn = null };
308. return api.makeObject(obj);
309. }
311. /// hl_time_timer_stop(id) — disarm and close. TRUE when this call was the one
312. /// that stopped it. The caller retires the event source FIRST (Timer.hl), so the
313. /// loop has already dropped this fd from its epoll set by the time it is closed.
314. export fn hl_time_timer_stop(argc: u32, argv: [*]const HlValue) callconv(.c) HlValue {
315. if (argc < 1 or argv[0].type != .hl_number) {
316. return api.makeError("hl:time timer stop: pass the id timer() returned");
317. }
318. const t = timerById(argv[0].data.number) orelse return api.makeBool(false);
319. const was_open = t.fd >= 0;
320. t.stopped = true;
321. if (t.fd >= 0) {
322. timerfdDisarm(t.fd);
323. _ = linux.close(t.fd);
324. t.fd = -1;
325. }
326. return api.makeBool(was_open);
327. }
329. /// hl_time_sleep(seconds) — BLOCKING, and that is the creator's ruling, not an
330. /// omission: *"sleep you need mostly for testing or debugging stuff, its what i
331. /// consider basic tools"*. It stops this thread, which inside a request handler
332. /// means the loop is stopped too; `after()` is the thing to use there, and
333. /// server.hl says so where an author will read it.
334. export fn hl_time_sleep(argc: u32, argv: [*]const HlValue) callconv(.c) HlValue {
335. if (argc < 1 or argv[0].type != .hl_number) {
336. return api.makeError("hl:time sleep: pass the duration in SECONDS (fractions allowed)");
337. }
338. const secs = argv[0].data.number;
339. if (!(secs == secs) or secs <= 0) return api.makeBool(false);
340. const ns: i64 = @intFromFloat(secs * 1_000_000_000.0);
341. // EINTR leaves the remainder; a signal must not silently shorten the sleep.
342. var req = linux.timespec{ .sec = @intCast(@divTrunc(ns, 1_000_000_000)), .nsec = @intCast(@mod(ns, 1_000_000_000)) };
343. var rem = linux.timespec{ .sec = 0, .nsec = 0 };
344. while (@as(isize, @bitCast(linux.nanosleep(&req, &rem))) != 0) {
345. if (rem.sec == 0 and rem.nsec == 0) break;
346. req = rem;
347. rem = .{ .sec = 0, .nsec = 0 };
348. }
349. return api.makeBool(true);
350. }
352. // ═══════════════════════════════════════════════════════════════════════════
353. // TIME ZONES (ticket #5)
354. // ═══════════════════════════════════════════════════════════════════════════
355. //
356. // The creator's ruling (ident.worldapi.org#14): "hybriel needs time zone
357. // support". Five calls, one primitive:
358. //
359. // hl_time_offset(ms, zone) → seconds EAST of UTC at that instant
360. // hl_time_local(ms, zone) → { year, month, day, hour, minute, second,
361. // millisecond, weekday, offset }
362. // hl_time_fromLocal(fields, zone) → epoch ms of that wall-clock reading
363. // hl_time_localTimestamp(ms, zone) → "YYYY-MM-DDTHH:MM:SS.mmm+HH:MM"
364. // hl_time_isZone(name) → Boolean
365. //
366. // THE DATABASE IS THE SYSTEM'S: /usr/share/zoneinfo, the TZif files (RFC 8536)
367. // every Linux ships, read with raw syscalls like the rest of this .so — no libc,
368. // no new dependency. A zone is parsed once and cached for the life of the
369. // process. The browser twin (server.js) asks Intl instead, and the two agree
370. // because everything EXCEPT the offset is computed by the same arithmetic on
371. // both sides: `offset()` is the only question either realm puts to its
372. // database, and `local`, `fromLocal` and `localTimestamp` are built on it.
373. //
374. // OFFSET LOOKUP, per RFC 8536: before the first transition, time type 0; between
375. // transitions, the type the last one selected; after the last, the footer's
376. // POSIX TZ rule (a "slim" TZif carries nothing else for the future), or the
377. // last type when there is no footer.
378. //
379. // Same threading assumption as `timestamp` above: a plugin call never yields and
380. // the runtime copies a returned value before the next call, so the results are
381. // rendered into module-level buffers and the zone cache has no lock.
383. const ZONEINFO = "/usr/share/zoneinfo/";
384. const MAX_MS: f64 = 8.64e15; // the range an ECMAScript Date (and Intl) accepts
386. const TzType = struct { utoff: i32, isdst: bool };
388. /// A POSIX TZ string's rule date: Jn (1..365, Feb 29 never counted), n (0..365,
389. /// Feb 29 counted) or Mm.w.d (weekday d of week w of month m; w=5 is "last").
390. const RuleDate = struct {
391. kind: enum { julian1, julian0, mwd } = .mwd,
392. n: i32 = 0,
393. m: i32 = 0,
394. w: i32 = 0,
395. d: i32 = 0,
396. /// local time of day the change happens, seconds (may be negative or > 24h)
397. time: i32 = 7200,
398. };
400. const PosixRule = struct {
401. std_off: i32 = 0, // seconds east of UTC
402. dst_off: i32 = 0,
403. has_dst: bool = false,
404. start: RuleDate = .{},
405. end: RuleDate = .{},
406. };
408. const Zone = struct {
409. trans: []i64,
410. idx: []u8,
411. types: []TzType,
412. rule: ?PosixRule,
413. };
415. var zones = std.StringHashMapUnmanaged(?*Zone).empty;
417. fn floorDiv(a: i64, b: i64) i64 {
418. return @divFloor(a, b);
419. }
421. /// Days since 1970-01-01 of a proleptic Gregorian date (H. Hinnant's
422. /// days_from_civil). `m` is 1..12; `d` may be any integer — it simply adds.
423. fn daysFromCivil(y0: i64, m: i64, d: i64) i64 {
424. const y = if (m <= 2) y0 - 1 else y0;
425. const era = floorDiv(y, 400);
426. const yoe = y - era * 400;
427. const mp = @mod(m + 9, 12);
428. const doy = @divFloor(153 * mp + 2, 5);
429. const doe = yoe * 365 + @divFloor(yoe, 4) - @divFloor(yoe, 100) + doy;
430. return era * 146097 + doe - 719468 + (d - 1);
431. }
433. const Civil = struct { y: i64, m: i64, d: i64 };
435. fn civilFromDays(z0: i64) Civil {
436. const z = z0 + 719468;
437. const era = floorDiv(z, 146097);
438. const doe = z - era * 146097;
439. const yoe = @divFloor(doe - @divFloor(doe, 1460) + @divFloor(doe, 36524) - @divFloor(doe, 146096), 365);
440. const doy = doe - (365 * yoe + @divFloor(yoe, 4) - @divFloor(yoe, 100));
441. const mp = @divFloor(5 * doy + 2, 153);
442. const d = doy - @divFloor(153 * mp + 2, 5) + 1;
443. const m = if (mp < 10) mp + 3 else mp - 9;
444. return .{ .y = if (m <= 2) yoe + era * 400 + 1 else yoe + era * 400, .m = m, .d = d };
445. }
447. fn isLeap(y: i64) bool {
448. return @mod(y, 4) == 0 and (@mod(y, 100) != 0 or @mod(y, 400) == 0);
449. }
451. /// Seconds since the epoch at which rule date `r` happens in year `y`, in the
452. /// local time whose offset is `off` (the offset in force just before it).
453. fn ruleInstant(r: RuleDate, y: i64, off: i32) i64 {
454. const jan1 = daysFromCivil(y, 1, 1);
455. const day: i64 = switch (r.kind) {
456. .julian1 => blk: {
457. var n: i64 = r.n - 1;
458. if (isLeap(y) and r.n >= 60) n += 1;
459. break :blk jan1 + n;
460. },
461. .julian0 => jan1 + r.n,
462. .mwd => blk: {
463. const first = daysFromCivil(y, r.m, 1);
464. // 1970-01-01 was a Thursday; POSIX d is 0 = Sunday
465. const wd_first = @mod(first + 4, 7);
466. var day = first + @mod(r.d - wd_first, 7) + (r.w - 1) * 7;
467. if (r.w == 5) {
468. const next = if (r.m == 12) daysFromCivil(y + 1, 1, 1) else daysFromCivil(y, r.m + 1, 1);
469. while (day >= next) day -= 7;
470. }
471. break :blk day;
472. },
473. };
474. return day * 86400 + r.time - off;
475. }
477. fn ruleOffset(r: PosixRule, t: i64) i32 {
478. if (!r.has_dst) return r.std_off;
479. const y = civilFromDays(floorDiv(t + r.std_off, 86400)).y;
480. const start = ruleInstant(r.start, y, r.std_off);
481. const end = ruleInstant(r.end, y, r.dst_off);
482. const in_dst = if (start < end) (t >= start and t < end) else !(t >= end and t < start);
483. return if (in_dst) r.dst_off else r.std_off;
484. }
486. fn zoneOffset(z: *const Zone, t: i64) i32 {
487. if (z.trans.len == 0) {
488. if (z.rule) |r| return ruleOffset(r, t);
489. return z.types[0].utoff;
490. }
491. if (t < z.trans[0]) return z.types[0].utoff;
492. if (t >= z.trans[z.trans.len - 1]) {
493. if (z.rule) |r| return ruleOffset(r, t);
494. return z.types[z.idx[z.idx.len - 1]].utoff;
495. }
496. var lo: usize = 0;
497. var hi: usize = z.trans.len - 1; // trans[lo] <= t < trans[hi]
498. while (hi - lo > 1) {
499. const mid = lo + (hi - lo) / 2;
500. if (z.trans[mid] <= t) lo = mid else hi = mid;
501. }
502. return z.types[z.idx[lo]].utoff;
503. }
505. // ── the POSIX TZ footer ─────────────────────────────────────────────────────
507. const Cursor = struct {
508. s: []const u8,
509. i: usize = 0,
510. fn peek(c: *Cursor) u8 {
511. return if (c.i < c.s.len) c.s[c.i] else 0;
512. }
513. fn num(c: *Cursor) ?i32 {
514. var v: i32 = 0;
515. const from = c.i;
516. while (c.i < c.s.len and c.s[c.i] >= '0' and c.s[c.i] <= '9') : (c.i += 1) {
517. v = v * 10 + @as(i32, c.s[c.i] - '0');
518. }
519. return if (c.i == from) null else v;
520. }
521. };
523. fn parseName(c: *Cursor) bool {
524. if (c.peek() == '<') {
525. while (c.i < c.s.len and c.s[c.i] != '>') c.i += 1;
526. if (c.peek() != '>') return false;
527. c.i += 1;
528. return true;
529. }
530. const from = c.i;
531. while (c.i < c.s.len and std.ascii.isAlphabetic(c.s[c.i])) c.i += 1;
532. return c.i - from >= 3;
533. }
535. /// [+-]hh[:mm[:ss]] → seconds, sign as written
536. fn parseHms(c: *Cursor) ?i32 {
537. var sign: i32 = 1;
538. if (c.peek() == '+') c.i += 1 else if (c.peek() == '-') {
539. sign = -1;
540. c.i += 1;
541. }
542. var v = (c.num() orelse return null) * 3600;
543. if (c.peek() == ':') {
544. c.i += 1;
545. v += (c.num() orelse return null) * 60;
546. if (c.peek() == ':') {
547. c.i += 1;
548. v += c.num() orelse return null;
549. }
550. }
551. return sign * v;
552. }
554. fn parseRuleDate(c: *Cursor) ?RuleDate {
555. var r = RuleDate{};
556. if (c.peek() == 'J') {
557. c.i += 1;
558. r.kind = .julian1;
559. r.n = c.num() orelse return null;
560. } else if (c.peek() == 'M') {
561. c.i += 1;
562. r.kind = .mwd;
563. r.m = c.num() orelse return null;
564. if (c.peek() != '.') return null;
565. c.i += 1;
566. r.w = c.num() orelse return null;
567. if (c.peek() != '.') return null;
568. c.i += 1;
569. r.d = c.num() orelse return null;
570. if (r.m < 1 or r.m > 12 or r.w < 1 or r.w > 5 or r.d > 6) return null;
571. } else {
572. r.kind = .julian0;
573. r.n = c.num() orelse return null;
574. }
575. if (c.peek() == '/') {
576. c.i += 1;
577. r.time = parseHms(c) orelse return null;
578. }
579. return r;
580. }
582. fn parsePosix(s: []const u8) ?PosixRule {
583. var c = Cursor{ .s = s };
584. var r = PosixRule{};
585. if (!parseName(&c)) return null;
586. // POSIX writes the offset WEST of UTC ("CET-1"); this plugin speaks east
587. r.std_off = -(parseHms(&c) orelse return null);
588. if (c.i == s.len) return r;
589. if (!parseName(&c)) return null;
590. r.has_dst = true;
591. r.dst_off = r.std_off + 3600;
592. if (c.peek() != ',' and c.i < s.len) r.dst_off = -(parseHms(&c) orelse return null);
593. if (c.peek() != ',') return null; // a DST name without rules: no reliable answer
594. c.i += 1;
595. r.start = parseRuleDate(&c) orelse return null;
596. if (c.peek() != ',') return null;
597. c.i += 1;
598. r.end = parseRuleDate(&c) orelse return null;
599. return r;
600. }
602. // ── TZif ────────────────────────────────────────────────────────────────────
604. fn be32(b: []const u8) i32 {
605. return std.mem.readInt(i32, b[0..4], .big);
606. }
608. fn be64(b: []const u8) i64 {
609. return std.mem.readInt(i64, b[0..8], .big);
610. }
612. /// A name the zone database may answer for: the shape of an IANA name, and
613. /// never a path out of the directory or one of its non-zone entries.
614. fn plausibleName(name: []const u8) bool {
615. if (name.len == 0 or name.len > 64) return false;
616. if (!std.ascii.isAlphabetic(name[0])) return false;
617. for (name) |ch| {
618. if (!(std.ascii.isAlphanumeric(ch) or ch == '/' or ch == '_' or ch == '-' or ch == '+')) return false;
619. }
620. if (std.mem.indexOf(u8, name, "//") != null or name[name.len - 1] == '/') return false;
621. // the directory's own furniture: alternative trees, and entries Intl rejects
622. const not_zones = [_][]const u8{ "posix/", "right/" };
623. for (not_zones) |p| if (std.mem.startsWith(u8, name, p)) return false;
624. const not_names = [_][]const u8{ "posixrules", "localtime", "Factory" };
625. for (not_names) |n| if (std.mem.eql(u8, name, n)) return false;
626. return true;
627. }
629. fn readZoneFile(name: []const u8) ?[]u8 {
630. var path_buf: [128]u8 = undefined;
631. const path = std.fmt.bufPrintZ(&path_buf, "{s}{s}", .{ ZONEINFO, name }) catch return null;
632. const rc = linux.open(path, .{ .ACCMODE = .RDONLY, .CLOEXEC = true }, 0);
633. const sfd: isize = @bitCast(rc);
634. if (sfd < 0) return null;
635. const fd: i32 = @intCast(sfd);
636. defer _ = linux.close(fd);
637. var out: std.ArrayList(u8) = .empty;
638. var buf: [8192]u8 = undefined;
639. while (true) {
640. const n: isize = @bitCast(linux.read(fd, &buf, buf.len));
641. if (n < 0) {
642. out.deinit(allocator);
643. return null; // EISDIR for "Europe", among others
644. }
645. if (n == 0) break;
646. out.appendSlice(allocator, buf[0..@intCast(n)]) catch {
647. out.deinit(allocator);
648. return null;
649. };
650. if (out.items.len > 1 << 20) break; // no zone is this large
651. }
652. return out.toOwnedSlice(allocator) catch null;
653. }
655. const Counts = struct { isut: usize, isstd: usize, leap: usize, time: usize, typ: usize, chr: usize };
657. fn header(b: []const u8) ?Counts {
658. if (b.len < 44 or !std.mem.eql(u8, b[0..4], "TZif")) return null;
659. const n = struct {
660. fn at(x: []const u8, o: usize) usize {
661. const v = be32(x[o..]);
662. return if (v < 0) 0 else @intCast(v);
663. }
664. };
665. return .{
666. .isut = n.at(b, 20),
667. .isstd = n.at(b, 24),
668. .leap = n.at(b, 28),
669. .time = n.at(b, 32),
670. .typ = n.at(b, 36),
671. .chr = n.at(b, 40),
672. };
673. }
675. fn parseTzif(b: []const u8) ?*Zone {
676. const h1 = header(b) orelse return null;
677. const version = b[4];
678. var p: usize = 44;
679. var tsize: usize = 4;
680. var h = h1;
681. if (version >= '2') {
682. // skip the 32-bit block; the 64-bit one follows with its own header
683. p += h1.time * 4 + h1.time + h1.typ * 6 + h1.chr + h1.leap * 8 + h1.isstd + h1.isut;
684. h = header(b[p..]) orelse return null;
685. p += 44;
686. tsize = 8;
687. }
688. const need = h.time * tsize + h.time + h.typ * 6 + h.chr + h.leap * (tsize + 4) + h.isstd + h.isut;
689. if (h.typ == 0 or b.len < p + need) return null;
691. const z = allocator.create(Zone) catch return null;
692. z.trans = allocator.alloc(i64, h.time) catch return null;
693. z.idx = allocator.alloc(u8, h.time) catch return null;
694. z.types = allocator.alloc(TzType, h.typ) catch return null;
695. for (0..h.time) |i| {
696. z.trans[i] = if (tsize == 8) be64(b[p + i * 8 ..]) else be32(b[p + i * 4 ..]);
697. }
698. p += h.time * tsize;
699. for (0..h.time) |i| {
700. z.idx[i] = b[p + i];
701. if (z.idx[i] >= h.typ) return null;
702. }
703. p += h.time;
704. for (0..h.typ) |i| {
705. const e = b[p + i * 6 ..];
706. z.types[i] = .{ .utoff = be32(e), .isdst = e[4] != 0 };
707. }
708. p += h.typ * 6 + h.chr + h.leap * (tsize + 4) + h.isstd + h.isut;
710. z.rule = null;
711. if (version >= '2' and p < b.len and b[p] == '\n') {
712. const rest = b[p + 1 ..];
713. if (std.mem.indexOfScalar(u8, rest, '\n')) |end| {
714. if (end > 0) z.rule = parsePosix(rest[0..end]);
715. }
716. }
717. return z;
718. }
720. /// The cached zone, or null when the database has no such zone.
721. fn zoneByName(name: []const u8) ?*Zone {
722. if (zones.get(name)) |cached| return cached;
723. const z: ?*Zone = if (!plausibleName(name)) null else blk: {
724. const bytes = readZoneFile(name) orelse break :blk null;
725. defer allocator.free(bytes);
726. break :blk parseTzif(bytes);
727. };
728. // unknown names are cached too, so a typo in a loop costs one open()
729. if (zones.count() < 4096) {
730. const key = allocator.dupe(u8, name) catch return z;
731. zones.put(allocator, key, z) catch allocator.free(key);
732. }
733. return z;
734. }
736. // ── the calls ───────────────────────────────────────────────────────────────
738. var err_buf: [160]u8 = undefined;
740. fn unknownZone(name: []const u8) HlValue {
741. const shown = if (name.len > 64) name[0..64] else name;
742. const msg = std.fmt.bufPrint(&err_buf, "hl:time: unknown time zone '{s}'", .{shown}) catch "hl:time: unknown time zone";
743. return api.makeError(msg);
744. }
746. const ZoneArg = union(enum) { zone: *Zone, err: HlValue };
748. fn zoneArg(argc: u32, argv: [*]const HlValue, at: u32) ZoneArg {
749. if (argc <= at or argv[at].type != .hl_string) {
750. return .{ .err = api.makeError("hl:time: pass the time zone as an IANA name, e.g. 'Europe/Vienna'") };
751. }
752. const s = argv[at].data.string;
753. const name = s.ptr[0..s.len];
754. return if (zoneByName(name)) |z| .{ .zone = z } else .{ .err = unknownZone(name) };
755. }
757. /// The instant argument: a finite epoch-ms Number within Date's range, floored
758. /// to a whole millisecond.
759. fn instantArg(argc: u32, argv: [*]const HlValue) ?i64 {
760. if (argc < 1 or argv[0].type != .hl_number) return null;
761. const v = argv[0].data.number;
762. if (!(v == v) or v > MAX_MS or v < -MAX_MS) return null;
763. return @intFromFloat(@floor(v));
764. }
766. const BAD_INSTANT = "hl:time: pass the instant in epoch milliseconds (what now() returns)";
768. fn offsetAtMs(z: *const Zone, ms: i64) i32 {
769. return zoneOffset(z, floorDiv(ms, 1000));
770. }
772. /// hl_time_offset(ms, zone) → seconds east of UTC in force at that instant
773. export fn hl_time_offset(argc: u32, argv: [*]const HlValue) callconv(.c) HlValue {
774. const ms = instantArg(argc, argv) orelse return api.makeError(BAD_INSTANT);
775. const z = switch (zoneArg(argc, argv, 1)) {
776. .zone => |z| z,
777. .err => |e| return e,
778. };
779. return api.makeNumber(@floatFromInt(offsetAtMs(z, ms)));
780. }
782. const FIELD_NAMES = [_][]const u8{ "year", "month", "day", "hour", "minute", "second", "millisecond", "weekday", "offset" };
783. var local_fields: [FIELD_NAMES.len]HlField = undefined;
784. var local_obj: HlObject = undefined;
786. /// hl_time_local(ms, zone) → the wall-clock reading in that zone at that instant
787. export fn hl_time_local(argc: u32, argv: [*]const HlValue) callconv(.c) HlValue {
788. const ms = instantArg(argc, argv) orelse return api.makeError(BAD_INSTANT);
789. const z = switch (zoneArg(argc, argv, 1)) {
790. .zone => |z| z,
791. .err => |e| return e,
792. };
793. const off = offsetAtMs(z, ms);
794. const local = ms + @as(i64, off) * 1000;
795. const days = floorDiv(local, 86_400_000);
796. const in_day = local - days * 86_400_000;
797. const c = civilFromDays(days);
798. const values = [_]i64{
799. c.y, c.m, c.d,
800. @divFloor(in_day, 3_600_000), @mod(@divFloor(in_day, 60_000), 60), @mod(@divFloor(in_day, 1000), 60),
801. @mod(in_day, 1000), @mod(days + 3, 7) + 1, // ISO: 1 = Monday … 7 = Sunday
802. off,
803. };
804. for (FIELD_NAMES, values, 0..) |k, v, i| {
805. local_fields[i] = .{ .key = hlStr(k), .value = api.makeNumber(@floatFromInt(v)) };
806. }
807. local_obj = .{ .fields = &local_fields, .field_count = local_fields.len, .deinit_fn = null };
808. return api.makeObject(&local_obj);
809. }
811. fn fieldNumber(obj: *const HlObject, key: []const u8, default: f64) ?f64 {
812. for (obj.fields[0..obj.field_count]) |f| {
813. if (!std.mem.eql(u8, f.key.ptr[0..f.key.len], key)) continue;
814. return switch (f.value.type) {
815. .hl_null => default,
816. .hl_number => if (f.value.data.number == f.value.data.number and
817. @abs(f.value.data.number) < 1e12) @floor(f.value.data.number) else null,
818. else => null,
819. };
820. }
821. return default;
822. }
824. /// The wall-clock reading as if it were UTC, in ms. Out-of-range fields carry
825. /// over the way Date.UTC's do: month 13 is January of the next year, minute 90
826. /// is an hour and a half.
827. fn wallMs(y: f64, mo: f64, d: f64, h: f64, mi: f64, s: f64, milli: f64) i64 {
828. const m0: i64 = @as(i64, @intFromFloat(mo)) - 1;
829. const yy: i64 = @as(i64, @intFromFloat(y)) + floorDiv(m0, 12);
830. const days = daysFromCivil(yy, @mod(m0, 12) + 1, @intFromFloat(d));
831. return days * 86_400_000 + @as(i64, @intFromFloat(h)) * 3_600_000 +
832. @as(i64, @intFromFloat(mi)) * 60_000 + @as(i64, @intFromFloat(s)) * 1000 + @as(i64, @intFromFloat(milli));
833. }
835. /// THE INVERSE, and the one place a zone can answer twice or not at all.
836. /// A reading inside a FOLD (the hour a fall-back repeats) is the EARLIER
837. /// instant; a reading inside a GAP (the hour a spring-forward skips) is moved
838. /// forward by the gap's length — 02:30 on Vienna's spring-forward night is
839. /// 03:30 CEST. That is Temporal's "compatible" disambiguation, and server.js
840. /// runs the same steps.
841. fn fromWall(z: *const Zone, wall: i64) i64 {
842. const before = offsetAtMs(z, wall - 86_400_000);
843. const after = offsetAtMs(z, wall + 86_400_000);
844. const a = wall - @as(i64, before) * 1000;
845. const b = wall - @as(i64, after) * 1000;
846. const a_ok = offsetAtMs(z, a) == before;
847. const b_ok = offsetAtMs(z, b) == after;
848. if (a_ok and b_ok) return @min(a, b);
849. if (a_ok) return a;
850. if (b_ok) return b;
851. return a; // the gap: read with the offset in force before it
852. }
854. /// hl_time_fromLocal(fields, zone) → epoch ms
855. export fn hl_time_fromLocal(argc: u32, argv: [*]const HlValue) callconv(.c) HlValue {
856. if (argc < 1 or argv[0].type != .hl_object) {
857. return api.makeError("hl:time fromLocal: pass the fields as { year, month, day, hour, minute, second, millisecond }");
858. }
859. const z = switch (zoneArg(argc, argv, 1)) {
860. .zone => |z| z,
861. .err => |e| return e,
862. };
863. const o = argv[0].data.object;
864. const bad = api.makeError("hl:time fromLocal: every field must be a Number (year is required)");
865. const y = fieldNumber(o, "year", std.math.nan(f64)) orelse return bad;
866. if (!(y == y)) return bad;
867. const mo = fieldNumber(o, "month", 1) orelse return bad;
868. const d = fieldNumber(o, "day", 1) orelse return bad;
869. const h = fieldNumber(o, "hour", 0) orelse return bad;
870. const mi = fieldNumber(o, "minute", 0) orelse return bad;
871. const s = fieldNumber(o, "second", 0) orelse return bad;
872. const milli = fieldNumber(o, "millisecond", 0) orelse return bad;
873. const wall = wallMs(y, mo, d, h, mi, s, milli);
874. if (@abs(wall) > 8_640_000_000_000_000 + 86_400_000) return api.makeError(BAD_INSTANT);
875. const ms = fromWall(z, wall);
876. if (@abs(ms) > 8_640_000_000_000_000) return api.makeError(BAD_INSTANT);
877. return api.makeNumber(@floatFromInt(ms));
878. }
880. var local_iso_buf: [48]u8 = undefined;
882. /// hl_time_localTimestamp(ms, zone) → ISO-8601 with the zone's offset
883. export fn hl_time_localTimestamp(argc: u32, argv: [*]const HlValue) callconv(.c) HlValue {
884. const ms = instantArg(argc, argv) orelse return api.makeError(BAD_INSTANT);
885. const z = switch (zoneArg(argc, argv, 1)) {
886. .zone => |z| z,
887. .err => |e| return e,
888. };
889. const off = offsetAtMs(z, ms);
890. const local = ms + @as(i64, off) * 1000;
891. const days = floorDiv(local, 86_400_000);
892. const in_day: u64 = @intCast(local - days * 86_400_000);
893. const c = civilFromDays(days);
895. var w: std.Io.Writer = .fixed(&local_iso_buf);
896. // 0000..9999 as four digits; beyond, ISO's expanded form (Date#toISOString's)
897. if (c.y >= 0 and c.y <= 9999) {
898. w.print("{d:0>4}", .{@as(u64, @intCast(c.y))}) catch unreachable;
899. } else {
900. w.print("{c}{d:0>6}", .{ @as(u8, if (c.y < 0) '-' else '+'), @abs(c.y) }) catch unreachable;
901. }
902. const abs_off: u64 = @abs(off);
903. w.print("-{d:0>2}-{d:0>2}T{d:0>2}:{d:0>2}:{d:0>2}.{d:0>3}{c}{d:0>2}:{d:0>2}", .{
904. @as(u64, @intCast(c.m)), @as(u64, @intCast(c.d)),
905. in_day / 3_600_000, in_day / 60_000 % 60,
906. in_day / 1000 % 60, in_day % 1000,
907. @as(u8, if (off < 0) '-' else '+'), abs_off / 3600,
908. abs_off / 60 % 60,
909. }) catch unreachable;
910. // an offset with seconds (local mean time before a zone's first rule)
911. if (abs_off % 60 != 0) w.print(":{d:0>2}", .{abs_off % 60}) catch unreachable;
912. return api.makeString(w.buffered());
913. }
915. /// hl_time_isZone(name) → true when the system's zone database knows the name
916. export fn hl_time_isZone(argc: u32, argv: [*]const HlValue) callconv(.c) HlValue {
917. if (argc < 1 or argv[0].type != .hl_string) return api.makeBool(false);
918. const s = argv[0].data.string;
919. return api.makeBool(zoneByName(s.ptr[0..s.len]) != null);
920. }