tracker

44.6 KB

1. // hl:fs plugin — native shared library
2. // Compiled to fs.so, loaded by runtime via dlopen
3. //
4. // Exports:
5. // hl_fs_file(path) → file descriptor with metadata + line iterator
6. // hl_fs_read_file(path) → entire file as string (raw bytes, unchecked)
7. // hl_fs_write_file(path, text, mode?) / hl_fs_write_file_hex(path, hex, mode?)
8. // hl_fs_append_file(path, text, mode?) / hl_fs_append_file_hex(path, hex, mode?)
9. // hl_fs_list_dir(path) → streaming directory iterator
11. const std = @import("std");
12. const api = @import("plugin_api");
14. const linux = std.os.linux;
16. const HlValue = api.HlValue;
17. const HlObject = api.HlObject;
18. const HlField = api.HlField;
19. const HlIterator = api.HlIterator;
20. const HlString = api.HlString;
22. // the plugins' allocator (plugin_api.zig)
23. const allocator = api.allocator;
25. // =========================================================================
26. // Path resolution (mission 068)
27. //
28. // CONTRACT: relative paths passed to hl:fs resolve against the MAIN SCRIPT's
29. // directory, not the process CWD — Hybriel path resolution is file-relative
30. // everywhere (import, inherit, plugin discovery), and fs follows suit.
31. // Absolute paths are used as-is. The runtime injects the script dir via the
32. // optional plugin hook hl_fs_set_script_dir right after dlopen.
33. // =========================================================================
35. var script_dir: ?[]u8 = null;
37. export fn hl_fs_set_script_dir(ptr: [*]const u8, len: usize) callconv(.c) void {
38. if (script_dir) |old| allocator.free(old);
39. script_dir = allocator.dupe(u8, ptr[0..len]) catch null;
40. }
42. /// Resolve a (possibly relative) path against the script dir. Returned slice
43. /// is allocated with the plugin allocator; caller frees.
44. fn resolvePath(path: []const u8) ?[]u8 {
45. if (path.len == 0) return allocator.dupe(u8, path) catch null;
46. if (path[0] == '/') return allocator.dupe(u8, path) catch null;
47. if (script_dir) |sd| {
48. return std.fmt.allocPrint(allocator, "{s}/{s}", .{ sd, path }) catch null;
49. }
50. return allocator.dupe(u8, path) catch null;
51. }
53. // =========================================================================
54. // Error values (mission 068): open failures are LOUD — api.makeError with
55. // the operation, the path as the caller wrote it, and the OS reason. The
56. // runtime turns a top-level error value into a located runtime error.
57. // =========================================================================
59. fn errnoText(errno: usize) []const u8 {
60. return switch (errno) {
61. 2 => "no such file or directory",
62. 13 => "permission denied",
63. 20 => "not a directory",
64. 21 => "is a directory",
65. else => "I/O error",
66. };
67. }
69. fn errDeinit(val: *api.HlValue) callconv(.c) void {
70. if (val.type == .hl_error) {
71. const s = val.data.string;
72. allocator.free(@constCast(s.ptr[0..s.len]));
73. }
74. }
76. fn makeOpenError(op: []const u8, path: []const u8, errno: usize) api.HlValue {
77. const msg = std.fmt.allocPrint(allocator, "{s}: cannot open '{s}' — {s} (errno {d}); relative paths resolve against the script's directory", .{ op, path, errnoText(errno), errno }) catch
78. return api.makeError("fs: cannot open file");
79. var v = api.makeError(msg);
80. v.deinit_fn = &errDeinit;
81. return v;
82. }
84. fn makeReadError(op: []const u8, path: []const u8, errno: usize) api.HlValue {
85. const msg = std.fmt.allocPrint(allocator, "{s}: cannot read '{s}' — {s} (errno {d})", .{ op, path, errnoText(errno), errno }) catch
86. return api.makeError("fs: cannot read file");
87. var v = api.makeError(msg);
88. v.deinit_fn = &errDeinit;
89. return v;
90. }
92. // =========================================================================
93. // hl_fs_file — file descriptor with metadata + line iterator
94. // =========================================================================
96. const FileIterState = struct {
97. fd: i32,
98. allocated_strings: std.array_list.Managed([]u8),
99. done: bool,
100. buf: [4096]u8,
101. buf_pos: usize,
102. buf_len: usize,
103. };
105. export fn hl_fs_file(argc: u32, argv: [*]const HlValue) callconv(.c) HlValue {
106. if (argc < 1 or argv[0].type != .hl_string) return api.makeError("fs.file expects a string path");
107. const path_str = argv[0].data.string;
108. const path = path_str.ptr[0..path_str.len];
110. // Resolve relative paths against the script dir; keep the caller's path
111. // for the descriptor's name/path fields.
112. const resolved = resolvePath(path) orelse return api.makeNull();
113. defer allocator.free(resolved);
115. // We need a null-terminated path for the OS
116. const path_z = allocator.dupeZ(u8, resolved) catch return api.makeNull();
117. defer allocator.free(path_z);
119. // Open file
120. const rc = linuxOpenRc(path_z, .{}, 0);
121. if (rc < 0) return makeOpenError("fs.file", path, @intCast(-rc));
122. const fd: i32 = @intCast(rc);
124. // Stat for size, chmod, uid, gid
125. var size: f64 = 0;
126. var chmod: f64 = 0;
127. var uid: f64 = 0;
128. var gid: f64 = 0;
129. var stat_ok = false;
131. var statx_buf: std.os.linux.Statx = undefined;
132. const statx_rc = std.os.linux.statx(
133. fd,
134. "",
135. std.os.linux.AT.EMPTY_PATH,
136. std.os.linux.STATX.BASIC_STATS,
137. &statx_buf,
138. );
139. if (statx_rc == 0) {
140. size = @floatFromInt(statx_buf.size);
141. chmod = @floatFromInt(statx_buf.mode & 0o7777);
142. uid = @floatFromInt(statx_buf.uid);
143. gid = @floatFromInt(statx_buf.gid);
144. stat_ok = true;
145. }
147. // Extract name from path
148. const name = if (std.mem.lastIndexOfScalar(u8, path, '/')) |idx|
149. path[idx + 1 ..]
150. else
151. path;
153. // Mime from extension
154. const mime = mimeFromName(name);
156. // Build fields: name, path, size, mime, chmod, user, group = 7 fields
157. const field_count: usize = 7;
158. const fields = allocator.alloc(HlField, field_count) catch return api.makeNull();
160. fields[0] = .{ .key = hlStr("name"), .value = api.makeString(name) };
161. fields[1] = .{ .key = hlStr("path"), .value = api.makeString(path) };
162. fields[2] = .{ .key = hlStr("size"), .value = api.makeNumber(size) };
163. fields[3] = .{ .key = hlStr("mime"), .value = api.makeString(mime) };
164. fields[4] = .{ .key = hlStr("chmod"), .value = api.makeNumber(chmod) };
165. if (stat_ok) {
166. fields[5] = .{ .key = hlStr("user"), .value = api.makeNumber(uid) };
167. fields[6] = .{ .key = hlStr("group"), .value = api.makeNumber(gid) };
168. } else {
169. fields[5] = .{ .key = hlStr("user"), .value = api.makeNull() };
170. fields[6] = .{ .key = hlStr("group"), .value = api.makeNull() };
171. }
173. const obj = allocator.create(HlObject) catch return api.makeNull();
174. obj.* = .{
175. .fields = fields.ptr,
176. .field_count = field_count,
177. .deinit_fn = &fileObjDeinit,
178. };
180. // Create line iterator
181. const iter_state = allocator.create(FileIterState) catch return api.makeNull();
182. iter_state.* = .{
183. .fd = fd,
184. .allocated_strings = std.array_list.Managed([]u8).init(allocator),
185. .done = false,
186. .buf = undefined,
187. .buf_pos = 0,
188. .buf_len = 0,
189. };
191. const iter = allocator.create(HlIterator) catch return api.makeNull();
192. iter.* = .{
193. .context = @ptrCast(iter_state),
194. .next_fn = &fileIterNext,
195. .deinit_fn = &fileIterDeinit,
196. };
198. // Return object — runtime will see it has both object fields and an iterator
199. // We pack the iterator pointer into the object by adding one more field
200. const full_fields = allocator.alloc(HlField, field_count + 1) catch return api.makeNull();
201. @memcpy(full_fields[0..field_count], fields);
202. full_fields[field_count] = .{ .key = hlStr("__iter"), .value = api.makeIterator(iter) };
204. // Free the original fields, use full_fields
205. allocator.free(fields);
206. obj.fields = full_fields.ptr;
207. obj.field_count = field_count + 1;
209. return api.makeObject(obj);
210. }
212. fn fileIterNext(ctx: ?*anyopaque) callconv(.c) HlValue {
213. const state: *FileIterState = @ptrCast(@alignCast(ctx orelse return api.makeNull()));
214. if (state.done) return api.makeNull();
216. var line_buf = std.array_list.Managed(u8).init(allocator);
218. while (true) {
219. if (state.buf_pos < state.buf_len) {
220. const remaining = state.buf[state.buf_pos..state.buf_len];
221. if (std.mem.indexOfScalar(u8, remaining, '\n')) |nl_pos| {
222. line_buf.appendSlice(remaining[0..nl_pos]) catch return api.makeNull();
223. state.buf_pos += nl_pos + 1;
224. break;
225. } else {
226. line_buf.appendSlice(remaining) catch return api.makeNull();
227. state.buf_pos = 0;
228. state.buf_len = 0;
229. }
230. }
232. // Read from file using posix read
233. const n = linuxRead(state.fd, &state.buf) orelse {
234. state.done = true;
235. break;
236. };
237. if (n == 0) {
238. state.done = true;
239. break;
240. }
241. state.buf_pos = 0;
242. state.buf_len = n;
243. }
245. if (line_buf.items.len == 0 and state.done) {
246. line_buf.deinit();
247. return api.makeNull();
248. }
250. const line = line_buf.toOwnedSlice() catch return api.makeNull();
251. state.allocated_strings.append(line) catch return api.makeNull();
252. return api.makeString(line);
253. }
255. fn fileIterDeinit(ctx: ?*anyopaque) callconv(.c) void {
256. const state: *FileIterState = @ptrCast(@alignCast(ctx orelse return));
257. _ = linux.close(state.fd);
258. for (state.allocated_strings.items) |s| {
259. allocator.free(s);
260. }
261. state.allocated_strings.deinit();
262. allocator.destroy(state);
263. }
265. fn fileObjDeinit(obj: *HlObject) callconv(.c) void {
266. const fields = obj.fields[0..obj.field_count];
267. // Check for iterator field and clean it up (only if not already nulled out by runtime)
268. for (fields) |field| {
269. if (field.value.type == .hl_iterator) {
270. const iter = field.value.data.iterator;
271. if (iter.deinit_fn) |deinit_fn| {
272. deinit_fn(iter.context);
273. }
274. allocator.destroy(iter);
275. }
276. }
277. allocator.free(fields);
278. allocator.destroy(obj);
279. }
281. // =========================================================================
282. // hl_fs_read_file — read entire file as string
283. // =========================================================================
285. fn readFileDeinit(val: *HlValue) callconv(.c) void {
286. if (val.type == .hl_string) {
287. const s = val.data.string;
288. allocator.free(@constCast(s.ptr[0..s.len]));
289. }
290. }
292. /// exists(path) → Boolean (mission 077, 074 GAP 8). The ONLY hl:fs entry point
293. /// that never errors: it answers a question, and "no" is an answer, not a
294. /// failure. Same script-relative resolution as everything else. Without it the
295. /// only way to test a path was to open it and survive the error — which is why
296. /// the retired live_server used to index `static/` blind instead of probing it.
297. export fn hl_fs_exists(argc: u32, argv: [*]const HlValue) callconv(.c) HlValue {
298. if (argc < 1 or argv[0].type != .hl_string) return api.makeBool(false);
299. const path_str = argv[0].data.string;
300. const path = path_str.ptr[0..path_str.len];
302. const resolved = resolvePath(path) orelse return api.makeBool(false);
303. defer allocator.free(resolved);
304. const path_z = allocator.dupeZ(u8, resolved) catch return api.makeBool(false);
305. defer allocator.free(path_z);
307. // statx, not open: a directory, a symlink target, a device — anything the
308. // OS can name — counts, and nothing is opened (no fd, no side effect).
309. var statx_buf: std.os.linux.Statx = undefined;
310. const rc = std.os.linux.statx(
311. std.os.linux.AT.FDCWD,
312. path_z,
313. 0,
314. std.os.linux.STATX.BASIC_STATS,
315. &statx_buf,
316. );
317. return api.makeBool(@as(isize, @bitCast(rc)) == 0);
318. }
320. export fn hl_fs_read_file(argc: u32, argv: [*]const HlValue) callconv(.c) HlValue {
321. if (argc < 1 or argv[0].type != .hl_string) return api.makeError("fs.readFile expects a string path");
322. const path_str = argv[0].data.string;
323. const path = path_str.ptr[0..path_str.len];
325. const resolved = resolvePath(path) orelse return api.makeNull();
326. defer allocator.free(resolved);
328. const path_z = allocator.dupeZ(u8, resolved) catch return api.makeNull();
329. defer allocator.free(path_z);
331. const rc = linuxOpenRc(path_z, .{}, 0);
332. if (rc < 0) return makeOpenError("fs.readFile", path, @intCast(-rc));
333. const fd: i32 = @intCast(rc);
334. defer _ = linux.close(fd);
336. // The whole file: no size cap (a 10 MiB cap once truncated silently, ticket #112).
337. // A failed read is an error naming the path, never a short string.
338. var content = std.array_list.Managed(u8).init(allocator);
339. defer content.deinit();
340. var buf: [65536]u8 = undefined;
341. while (true) {
342. const n_read: isize = @bitCast(linux.read(fd, &buf, buf.len));
343. if (n_read == 0) break;
344. if (n_read < 0) {
345. const errno: usize = @intCast(-n_read);
346. if (errno == @intFromEnum(linux.E.INTR)) continue;
347. return makeReadError("fs.readFile", path, errno);
348. }
349. content.appendSlice(buf[0..@intCast(n_read)]) catch return api.makeError("fs.readFile: out of memory reading the file");
350. }
352. const result_slice = content.toOwnedSlice() catch return api.makeNull();
353. var result = api.makeString(result_slice);
354. result.deinit_fn = &readFileDeinit;
355. return result;
356. }
358. // =========================================================================
359. // hl_fs_list_dir — streaming directory iterator with metadata
360. // =========================================================================
362. const DirIterState = struct {
363. fd: i32,
364. base_path: []const u8,
365. allocated_strings: std.array_list.Managed([]u8),
366. // Linux getdents64 buffer
367. dents_buf: [4096]u8,
368. dents_pos: usize,
369. dents_len: usize,
370. done: bool,
371. };
373. export fn hl_fs_list_dir(argc: u32, argv: [*]const HlValue) callconv(.c) HlValue {
374. if (argc < 1 or argv[0].type != .hl_string) return api.makeError("fs.listDir expects a string path");
375. const path_str = argv[0].data.string;
376. const path = path_str.ptr[0..path_str.len];
378. const resolved = resolvePath(path) orelse return api.makeNull();
379. defer allocator.free(resolved);
381. const path_z = allocator.dupeZ(u8, resolved) catch return api.makeNull();
382. defer allocator.free(path_z);
384. const rc = linuxOpenRc(path_z, .{ .DIRECTORY = true }, 0);
385. if (rc < 0) return makeOpenError("fs.listDir", path, @intCast(-rc));
386. const fd: i32 = @intCast(rc);
388. const path_copy = allocator.dupe(u8, path) catch return api.makeNull();
390. const state = allocator.create(DirIterState) catch return api.makeNull();
391. state.* = .{
392. .fd = fd,
393. .base_path = path_copy,
394. .allocated_strings = std.array_list.Managed([]u8).init(allocator),
395. .dents_buf = undefined,
396. .dents_pos = 0,
397. .dents_len = 0,
398. .done = false,
399. };
401. const iter = allocator.create(HlIterator) catch return api.makeNull();
402. iter.* = .{
403. .context = @ptrCast(state),
404. .next_fn = &dirIterNext,
405. .deinit_fn = &dirIterDeinit,
406. };
408. return api.makeIterator(iter);
409. }
411. fn dirIterNext(ctx: ?*anyopaque) callconv(.c) HlValue {
412. const state: *DirIterState = @ptrCast(@alignCast(ctx orelse return api.makeNull()));
413. if (state.done) return api.makeNull();
415. while (true) {
416. // Need more directory entries?
417. if (state.dents_pos >= state.dents_len) {
418. const rc = std.os.linux.getdents64(state.fd, &state.dents_buf, state.dents_buf.len);
419. if (@as(isize, @bitCast(rc)) <= 0) {
420. state.done = true;
421. return api.makeNull();
422. }
423. state.dents_len = rc;
424. state.dents_pos = 0;
425. }
427. // Parse next dirent64
428. const entry_ptr: *align(1) std.os.linux.dirent64 = @ptrCast(&state.dents_buf[state.dents_pos]);
429. state.dents_pos += entry_ptr.reclen;
431. // Get name
432. const name_ptr: [*]const u8 = @ptrCast(&entry_ptr.name);
433. const name_len = std.mem.indexOfScalar(u8, name_ptr[0..256], 0) orelse continue;
434. const name = name_ptr[0..name_len];
436. // Skip . and ..
437. if (std.mem.eql(u8, name, ".") or std.mem.eql(u8, name, "..")) continue;
439. const name_copy = allocator.dupe(u8, name) catch return api.makeNull();
440. state.allocated_strings.append(name_copy) catch return api.makeNull();
442. // Build full path
443. const full_path = std.fmt.allocPrint(allocator, "{s}/{s}", .{ state.base_path, name }) catch return api.makeNull();
444. state.allocated_strings.append(full_path) catch return api.makeNull();
446. // Entry type from d_type
447. const kind_str: []const u8 = switch (entry_ptr.type) {
448. std.os.linux.DT.DIR => "directory",
449. std.os.linux.DT.REG => "file",
450. std.os.linux.DT.LNK => "symlink",
451. else => "other",
452. };
454. // Stat for size, chmod, uid, gid
455. var size: f64 = 0;
456. var chmod: f64 = 0;
457. var e_uid: f64 = 0;
458. var e_gid: f64 = 0;
460. // null-terminate name for statx
461. var name_z_buf: [256]u8 = undefined;
462. if (name.len < name_z_buf.len) {
463. @memcpy(name_z_buf[0..name.len], name);
464. name_z_buf[name.len] = 0;
466. var statx_buf: std.os.linux.Statx = undefined;
467. const src = std.os.linux.statx(
468. state.fd,
469. @ptrCast(name_z_buf[0 .. name.len + 1]),
470. 0,
471. std.os.linux.STATX.BASIC_STATS,
472. &statx_buf,
473. );
474. if (src == 0) {
475. size = @floatFromInt(statx_buf.size);
476. chmod = @floatFromInt(statx_buf.mode & 0o7777);
477. e_uid = @floatFromInt(statx_buf.uid);
478. e_gid = @floatFromInt(statx_buf.gid);
479. }
480. }
482. const mime = mimeFromName(name_copy);
484. // Build object: name, path, type, size, mime, chmod, user, group
485. // The runtime's hlObjectToValue will call entryObjDeinit after conversion,
486. // so these objects are freed immediately upon consumption.
487. const field_count: usize = 8;
488. const fields = allocator.alloc(HlField, field_count) catch return api.makeNull();
489. fields[0] = .{ .key = hlStr("name"), .value = api.makeString(name_copy) };
490. fields[1] = .{ .key = hlStr("path"), .value = api.makeString(full_path) };
491. fields[2] = .{ .key = hlStr("type"), .value = api.makeString(kind_str) };
492. fields[3] = .{ .key = hlStr("size"), .value = api.makeNumber(size) };
493. fields[4] = .{ .key = hlStr("mime"), .value = api.makeString(mime) };
494. fields[5] = .{ .key = hlStr("chmod"), .value = api.makeNumber(chmod) };
495. fields[6] = .{ .key = hlStr("user"), .value = api.makeNumber(e_uid) };
496. fields[7] = .{ .key = hlStr("group"), .value = api.makeNumber(e_gid) };
498. const obj = allocator.create(HlObject) catch return api.makeNull();
499. obj.* = .{
500. .fields = fields.ptr,
501. .field_count = field_count,
502. .deinit_fn = &entryObjDeinit,
503. };
505. return api.makeObject(obj);
506. }
507. }
509. fn entryObjDeinit(obj: *HlObject) callconv(.c) void {
510. allocator.free(obj.fields[0..obj.field_count]);
511. allocator.destroy(obj);
512. }
514. fn dirIterDeinit(ctx: ?*anyopaque) callconv(.c) void {
515. const state: *DirIterState = @ptrCast(@alignCast(ctx orelse return));
516. _ = linux.close(state.fd);
517. for (state.allocated_strings.items) |s| {
518. allocator.free(s);
519. }
520. state.allocated_strings.deinit();
521. allocator.free(@constCast(state.base_path));
522. allocator.destroy(state);
523. }
525. // =========================================================================
526. // Helpers
527. // =========================================================================
529. /// Raw open: >= 0 is the fd, < 0 is -errno.
530. fn linuxOpenRc(path_z: [*:0]const u8, flags: linux.O, mode: u32) isize {
531. const rc = linux.open(path_z, flags, mode);
532. return @bitCast(rc);
533. }
535. fn linuxRead(fd: i32, buf: []u8) ?usize {
536. const rc = linux.read(fd, buf.ptr, buf.len);
537. if (@as(isize, @bitCast(rc)) <= 0) return null;
538. return rc;
539. }
541. fn hlStr(comptime s: []const u8) HlString {
542. return .{ .ptr = s.ptr, .len = s.len };
543. }
545. fn mimeFromName(name: []const u8) []const u8 {
546. const ext = if (std.mem.lastIndexOfScalar(u8, name, '.')) |dot|
547. name[dot..]
548. else
549. return "application/octet-stream";
551. if (std.mem.eql(u8, ext, ".txt")) return "text/plain";
552. if (std.mem.eql(u8, ext, ".html") or std.mem.eql(u8, ext, ".htm")) return "text/html";
553. if (std.mem.eql(u8, ext, ".css")) return "text/css";
554. if (std.mem.eql(u8, ext, ".js")) return "text/javascript";
555. if (std.mem.eql(u8, ext, ".json")) return "application/json";
556. if (std.mem.eql(u8, ext, ".xml")) return "application/xml";
557. if (std.mem.eql(u8, ext, ".png")) return "image/png";
558. if (std.mem.eql(u8, ext, ".jpg") or std.mem.eql(u8, ext, ".jpeg")) return "image/jpeg";
559. if (std.mem.eql(u8, ext, ".gif")) return "image/gif";
560. if (std.mem.eql(u8, ext, ".svg")) return "image/svg+xml";
561. if (std.mem.eql(u8, ext, ".pdf")) return "application/pdf";
562. if (std.mem.eql(u8, ext, ".zip")) return "application/zip";
563. if (std.mem.eql(u8, ext, ".gz")) return "application/gzip";
564. if (std.mem.eql(u8, ext, ".mp3")) return "audio/mpeg";
565. if (std.mem.eql(u8, ext, ".mp4")) return "video/mp4";
566. if (std.mem.eql(u8, ext, ".wasm")) return "application/wasm";
567. if (std.mem.eql(u8, ext, ".hl")) return "text/x-hybriel";
568. if (std.mem.eql(u8, ext, ".md")) return "text/markdown";
569. if (std.mem.eql(u8, ext, ".yml") or std.mem.eql(u8, ext, ".yaml")) return "text/yaml";
570. if (std.mem.eql(u8, ext, ".toml")) return "application/toml";
571. if (std.mem.eql(u8, ext, ".csv")) return "text/csv";
572. if (std.mem.eql(u8, ext, ".ts")) return "text/typescript";
573. if (std.mem.eql(u8, ext, ".c") or std.mem.eql(u8, ext, ".h")) return "text/x-c";
574. if (std.mem.eql(u8, ext, ".zig")) return "text/x-zig";
575. if (std.mem.eql(u8, ext, ".rs")) return "text/x-rust";
576. if (std.mem.eql(u8, ext, ".py")) return "text/x-python";
577. if (std.mem.eql(u8, ext, ".sh")) return "text/x-shellscript";
578. if (std.mem.eql(u8, ext, ".sql")) return "application/sql";
579. if (std.mem.eql(u8, ext, ".webp")) return "image/webp";
580. if (std.mem.eql(u8, ext, ".ico")) return "image/x-icon";
581. if (std.mem.eql(u8, ext, ".woff2")) return "font/woff2";
582. if (std.mem.eql(u8, ext, ".woff")) return "font/woff";
583. if (std.mem.eql(u8, ext, ".ttf")) return "font/ttf";
584. return "application/octet-stream";
585. }
587. // ── fs.watch: an inotify LOOP SOURCE (the dev-reload bell) ───────────────────
588. // `watch(path)` returns an event-loop source whose wake_fd IS the inotify fd,
589. // so the loop's own epoll_wait wakes on a save — no polling anywhere. Watches
590. // the directory RECURSIVELY at registration (dot-dirs skipped); directories
591. // created afterwards are picked up the next time the app is restarted, which
592. // is the honest v1 for a dev tool.
593. //
594. // EXCLUSIONS (mission 266). `watch(path, exclude)` takes a second argument —
595. // a path STRING or a LIST of them, the same either-shape the plugin surface
596. // already uses in `hl_proc_spawn` — naming directories the descent must not
597. // enter. One argument still means "watch everything": the argument is optional
598. // and a null is the same as absent.
599. //
600. // This exists because a program that knows, at startup, about a directory it
601. // will write to constantly (hl:web's session store is the first) had NO way to
602. // say so. The only skip the walker possessed was "the name starts with a dot",
603. // so the framework's advice was to RENAME the directory — a lecture standing
604. // in for a fix. The dot-dir skip STAYS; `.git` is its reason and it is a good
605. // one. This is a second, explicit reason to skip, not a replacement.
607. const WatchState = struct {
608. ifd: i32,
609. buf: [4096]u8 align(4) = undefined,
610. len: usize = 0,
611. pos: usize = 0,
612. };
614. /// LEXICAL path normalisation — collapses `//` and resolves `.` / `..`
615. /// without touching the filesystem. It must be lexical: an excluded directory
616. /// need not exist yet at the moment the watch is armed (hl:web resolves its
617. /// session dir before it creates it), and realpath(2) on a missing path fails.
618. /// Both the watch root and every exclusion go through this, so the comparison
619. /// below is between two paths written the same way.
620. fn normalizePath(path: []const u8) ?[]u8 {
621. const absolute = path.len > 0 and path[0] == '/';
622. var parts = std.ArrayListUnmanaged([]const u8).empty;
623. defer parts.deinit(allocator);
624. var it = std.mem.tokenizeScalar(u8, path, '/');
625. while (it.next()) |seg| {
626. if (std.mem.eql(u8, seg, ".")) continue;
627. if (std.mem.eql(u8, seg, "..")) {
628. if (parts.items.len > 0 and !std.mem.eql(u8, parts.items[parts.items.len - 1], "..")) {
629. _ = parts.pop();
630. continue;
631. }
632. if (absolute) continue; // ".." above "/" is "/"
633. }
634. parts.append(allocator, seg) catch return null;
635. }
636. var out = std.ArrayListUnmanaged(u8).empty;
637. defer out.deinit(allocator);
638. for (parts.items, 0..) |seg, i| {
639. if (absolute or i > 0) out.append(allocator, '/') catch return null;
640. out.appendSlice(allocator, seg) catch return null;
641. }
642. if (out.items.len == 0) out.appendSlice(allocator, if (absolute) "/" else ".") catch return null;
643. return allocator.dupe(u8, out.items) catch null;
644. }
646. /// Is `child` the directory `root`, or somewhere under it? Both must already
647. /// be normalised. A bare `startsWith` would call `/a/sessions-old` a child of
648. /// `/a/sessions`, which is the whole reason this is a function: the byte after
649. /// the prefix has to BE a separator.
650. fn pathIsInside(child: []const u8, root: []const u8) bool {
651. if (root.len == 0) return false;
652. if (std.mem.eql(u8, child, root)) return true;
653. if (child.len <= root.len) return false;
654. if (!std.mem.startsWith(u8, child, root)) return false;
655. if (root[root.len - 1] == '/') return true; // root is "/" itself
656. return child[root.len] == '/';
657. }
659. fn addWatchesRecursive(ifd: i32, dir_path: []const u8, depth: u32, excludes: []const []const u8) void {
660. if (depth > 8) return;
661. // The SECOND reason to skip a directory (mission 266). `dir_path` is
662. // normalised: the root was normalised before the first call and every
663. // child below is that root plus one plain name.
664. for (excludes) |ex| if (pathIsInside(dir_path, ex)) return;
665. const path_z = allocator.dupeZ(u8, dir_path) catch return;
666. defer allocator.free(path_z);
667. const mask: u32 = linux.IN.CLOSE_WRITE | linux.IN.CREATE | linux.IN.DELETE | linux.IN.MOVED_TO | linux.IN.MOVED_FROM;
668. _ = linux.inotify_add_watch(ifd, path_z, mask);
670. // The descent walks getdents64 directly, like hl_fs_list_dir does — this
671. // plugin speaks raw syscalls throughout and never pulls in std.fs.
672. const rc = linuxOpenRc(path_z, .{ .DIRECTORY = true }, 0);
673. if (rc < 0) return;
674. const fd: i32 = @intCast(rc);
675. defer _ = linux.close(fd);
677. var dents: [4096]u8 align(8) = undefined;
678. while (true) {
679. const got = linux.getdents64(fd, &dents, dents.len);
680. if (@as(isize, @bitCast(got)) <= 0) break;
681. var pos: usize = 0;
682. while (pos < got) {
683. const entry: *align(1) linux.dirent64 = @ptrCast(&dents[pos]);
684. pos += entry.reclen;
685. if (entry.type != linux.DT.DIR) continue;
686. const name_ptr: [*]const u8 = @ptrCast(&entry.name);
687. const name_len = std.mem.indexOfScalar(u8, name_ptr[0..256], 0) orelse continue;
688. const name = name_ptr[0..name_len];
689. // "." and ".." would recurse forever; every other dot-dir is noise
690. // for a dev watcher (.git alone would cost thousands of watches).
691. if (name.len == 0 or name[0] == '.') continue;
692. const child = std.fmt.allocPrint(allocator, "{s}/{s}", .{ dir_path, name }) catch continue;
693. defer allocator.free(child);
694. addWatchesRecursive(ifd, child, depth + 1, excludes);
695. }
696. }
697. }
699. /// One exclusion, resolved against the script dir like every other hl:fs path
700. /// and then normalised. Appends nothing on an empty string.
701. fn appendExclusion(list: *std.ArrayListUnmanaged([]u8), raw: []const u8) bool {
702. if (raw.len == 0) return true;
703. const resolved = resolvePath(raw) orelse return false;
704. defer allocator.free(resolved);
705. const norm = normalizePath(resolved) orelse return false;
706. list.append(allocator, norm) catch {
707. allocator.free(norm);
708. return false;
709. };
710. return true;
711. }
713. export fn hl_fs_watch(argc: u32, argv: [*]const HlValue) callconv(.c) HlValue {
714. if (argc < 1 or argv[0].type != .hl_string) return api.makeError("hl:fs: watch(path) needs a path string");
715. const raw = argv[0].data.string.ptr[0..argv[0].data.string.len];
716. const resolved = resolvePath(raw) orelse return api.makeError("hl:fs: watch: could not resolve the path");
717. defer allocator.free(resolved);
718. const path = normalizePath(resolved) orelse return api.makeError("hl:fs: watch: could not resolve the path");
719. defer allocator.free(path);
721. // THE OPTIONAL SECOND ARGUMENT: absent or null → watch everything, exactly
722. // as before. A string is one directory; an object with numeric keys is the
723. // loader's list shape (`hl_proc_spawn` reads its argv list the same way).
724. var excludes = std.ArrayListUnmanaged([]u8).empty;
725. defer {
726. for (excludes.items) |e| allocator.free(e);
727. excludes.deinit(allocator);
728. }
729. if (argc >= 2) {
730. switch (argv[1].type) {
731. .hl_null => {},
732. .hl_string => {
733. const sv = argv[1].data.string;
734. if (!appendExclusion(&excludes, sv.ptr[0..sv.len])) return api.makeError("hl:fs: out of memory");
735. },
736. .hl_object => {
737. const obj_in = argv[1].data.object;
738. for (obj_in.fields[0..obj_in.field_count]) |field| {
739. if (field.value.type == .hl_null) continue;
740. if (field.value.type != .hl_string) return api.makeError("hl:fs: watch(path, exclude): every exclusion must be a path string");
741. const sv = field.value.data.string;
742. if (!appendExclusion(&excludes, sv.ptr[0..sv.len])) return api.makeError("hl:fs: out of memory");
743. }
744. },
745. else => return api.makeError("hl:fs: watch(path, exclude): exclude is a path string or a list of path strings"),
746. }
747. }
749. const rc = linux.inotify_init1(linux.IN.NONBLOCK);
750. const ifd: i32 = @intCast(@as(isize, @bitCast(rc)));
751. if (ifd < 0) return api.makeError("hl:fs: watch: inotify unavailable");
752. addWatchesRecursive(ifd, path, 0, excludes.items);
754. const state = allocator.create(WatchState) catch return api.makeError("hl:fs: out of memory");
755. state.* = .{ .ifd = ifd };
756. const iter = allocator.create(HlIterator) catch return api.makeError("hl:fs: out of memory");
757. iter.* = .{
758. .context = @ptrCast(state),
759. .next_fn = &watchTryNext, // non-blocking either way — event loop only
760. .try_next_fn = &watchTryNext,
761. .deinit_fn = &watchDeinit,
762. .wake_fd = ifd,
763. };
764. return api.makeIterator(iter);
765. }
767. fn watchTryNext(ctx: ?*anyopaque) callconv(.c) HlValue {
768. const st: *WatchState = @ptrCast(@alignCast(ctx orelse return api.makeNull()));
769. if (st.pos >= st.len) {
770. const r = linux.read(st.ifd, &st.buf, st.buf.len);
771. const n: isize = @bitCast(r);
772. if (n <= 0) return api.makeNull(); // EAGAIN: drained
773. st.len = @intCast(n);
774. st.pos = 0;
775. }
776. // one inotify_event: wd(i32) mask(u32) cookie(u32) len(u32) name[len]
777. const base = st.pos;
778. if (st.len - base < 16) {
779. st.pos = st.len;
780. return api.makeNull();
781. }
782. const name_len = std.mem.readInt(u32, st.buf[base + 12 ..][0..4], .little);
783. const name_start = base + 16;
784. var name: []const u8 = "";
785. if (name_len > 0 and name_start + name_len <= st.len) {
786. const raw_name = st.buf[name_start .. name_start + name_len];
787. name = std.mem.sliceTo(raw_name, 0);
788. }
789. st.pos = name_start + name_len;
791. const fields = allocator.alloc(api.HlField, 1) catch return api.makeNull();
792. const name_copy = allocator.dupe(u8, name) catch {
793. allocator.free(fields);
794. return api.makeNull();
795. };
796. fields[0] = .{ .key = hlStr("name"), .value = api.makeString(name_copy) };
797. const obj = allocator.create(api.HlObject) catch {
798. allocator.free(name_copy);
799. allocator.free(fields);
800. return api.makeNull();
801. };
802. obj.* = .{ .fields = fields.ptr, .field_count = 1, .deinit_fn = &watchEventDeinit };
803. return api.makeObject(obj);
804. }
806. /// An event is the loader's to copy and ours to free (the emit soak, 2026-10-02): with
807. /// no deinit, every inotify event of the dev watcher — each write a db makes under the
808. /// watched root — kept its name, its field and its object for good.
809. fn watchEventDeinit(obj: *api.HlObject) callconv(.c) void {
810. const sv = obj.fields[0].value.data.string;
811. allocator.free(@constCast(sv.ptr)[0..sv.len]);
812. allocator.free(obj.fields[0..obj.field_count]);
813. allocator.destroy(obj);
814. }
816. fn watchDeinit(ctx: ?*anyopaque) callconv(.c) void {
817. const st: *WatchState = @ptrCast(@alignCast(ctx orelse return));
818. _ = linux.close(st.ifd);
819. allocator.destroy(st);
820. }
822. // =========================================================================
823. // THE WRITE SURFACE (2026-08-28)
824. //
825. // hl:fs was READ-ONLY until this block: file, readFile, listDir, exists,
826. // watch. It could report a file's `chmod` and never set one. Session
827. // persistence is the first thing in this tree that has to put bytes on a
828. // disk, and the rule when the framework can do something the language
829. // cannot is that the LANGUAGE is missing it — so the capability lands here,
830. // as an ordinary hl:fs surface any program can use, not as a private hook
831. // the session store reaches through.
832. //
833. // Three calls, and the shape of each is a decision:
834. //
835. // writeFile(path, contents, mode?) ATOMIC. Writes a sibling temp file,
836. // fsyncs it, then rename()s it over the target — so a reader sees
837. // either the whole previous file or the whole new one, never a torn
838. // one. A half-written session file that revives as garbage is a
839. // silent logout, and the crash that produces it is exactly the crash
840. // nobody can reproduce. rename(2) within one directory is atomic on
841. // every filesystem Linux ships; that is the whole reason the temp
842. // file is a SIBLING rather than in /tmp (a cross-device rename fails).
843. // mkDir(path, mode?) recursive, and succeeds when the
844. // directory is already there — the caller wants it to exist, not to
845. // be the one who created it.
846. // remove(path) IDEMPOTENT: true when the path is
847. // gone on return, including when it was already gone. A sweep
848. // deleting an expired file must not fail because something else
849. // deleted it first.
850. //
851. // MODES ARE EXPLICIT AND DEFAULT TIGHT. hybrilior passes no mode anywhere,
852. // so its session files land at whatever the umask says — 0644 on a shared
853. // box, i.e. every session on the machine readable by every other tenant.
854. // Here the default is 0600 for a file and 0700 for a directory, and a
855. // caller who wants them looser has to say so. This is not the kind of bug
856. // that shows up in a test; it shows up in someone else's logs.
857. // =========================================================================
859. fn makeWriteError(op: []const u8, path: []const u8, errno: usize) api.HlValue {
860. const msg = std.fmt.allocPrint(allocator, "{s}: cannot write '{s}' — {s} (errno {d}); relative paths resolve against the script's directory", .{ op, path, errnoText(errno), errno }) catch
861. return api.makeError("fs: write failed");
862. var v = api.makeError(msg);
863. v.deinit_fn = &errDeinit;
864. return v;
865. }
867. /// mkdir every missing component of `path`. Returns 0, or the errno of the
868. /// first component that could not be created for a reason other than "it is
869. /// already there".
870. fn mkdirRecursive(path: []const u8, mode: u32) usize {
871. if (path.len == 0) return 0;
872. const buf = allocator.dupeZ(u8, path) catch return 12; // ENOMEM
873. defer allocator.free(buf);
875. // Walk the separators left to right, creating each prefix in turn. Index
876. // 0 is skipped so a leading '/' is never itself a component to create.
877. var i: usize = 1;
878. while (i <= buf.len) : (i += 1) {
879. const at_end = i == buf.len;
880. if (!at_end and buf[i] != '/') continue;
881. if (!at_end) buf[i] = 0;
882. const rc: isize = @bitCast(linux.mkdir(buf.ptr, mode));
883. if (!at_end) buf[i] = '/';
884. if (rc < 0) {
885. const errno: usize = @intCast(-rc);
886. // EEXIST is the success case: the caller wants it to exist.
887. if (errno != 17) return errno;
888. }
889. }
890. return 0;
891. }
893. export fn hl_fs_mk_dir(argc: u32, argv: [*]const HlValue) callconv(.c) HlValue {
894. if (argc < 1 or argv[0].type != .hl_string) return api.makeError("fs.mkDir expects a string path");
895. const path_str = argv[0].data.string;
896. const path = path_str.ptr[0..path_str.len];
898. var mode: u32 = 0o700;
899. if (argc >= 2 and argv[1].type == .hl_number) mode = @intFromFloat(argv[1].data.number);
901. const resolved = resolvePath(path) orelse return api.makeError("fs.mkDir: out of memory");
902. defer allocator.free(resolved);
904. const errno = mkdirRecursive(resolved, mode);
905. if (errno != 0) return makeWriteError("fs.mkDir", path, errno);
906. return api.makeBool(true);
907. }
909. const write_usage = "fs.writeFile expects (String path, String or Bytes contents, Number mode?)";
911. export fn hl_fs_write_file(argc: u32, argv: [*]const HlValue) callconv(.c) HlValue {
912. if (argc < 2 or argv[0].type != .hl_string or argv[1].type != .hl_string) {
913. return api.makeError(write_usage);
914. }
915. const path_str = argv[0].data.string;
916. const body_str = argv[1].data.string;
917. return writeWhole(path_str.ptr[0..path_str.len], body_str.ptr[0..body_str.len], modeArg(argc, argv));
918. }
920. /// hl_fs_write_file_hex(path, hex, mode?) — writeFile with a Bytes (ticket
921. /// #88): a Bytes crosses the plugin boundary as its hex text (the ABI has no
922. /// Bytes, as hl:proc's write_hex says), is decoded here and written raw.
923. export fn hl_fs_write_file_hex(argc: u32, argv: [*]const HlValue) callconv(.c) HlValue {
924. if (argc < 2 or argv[0].type != .hl_string or argv[1].type != .hl_string) {
925. return api.makeError(write_usage);
926. }
927. const path_str = argv[0].data.string;
928. const hex = argv[1].data.string.ptr[0..argv[1].data.string.len];
929. const raw = allocator.alloc(u8, hex.len / 2) catch return api.makeError("fs.writeFile: out of memory");
930. defer allocator.free(raw);
931. _ = std.fmt.hexToBytes(raw, hex) catch return api.makeError("fs.writeFile: not a Bytes");
932. return writeWhole(path_str.ptr[0..path_str.len], raw, modeArg(argc, argv));
933. }
935. fn modeArg(argc: u32, argv: [*]const HlValue) u32 {
936. if (argc >= 3 and argv[2].type == .hl_number) return @intFromFloat(argv[2].data.number);
937. return 0o600;
938. }
940. fn writeWhole(path: []const u8, body: []const u8, mode: u32) HlValue {
941. const resolved = resolvePath(path) orelse return api.makeError("fs.writeFile: out of memory");
942. defer allocator.free(resolved);
944. // The temp name is a SIBLING (see the block comment): rename(2) is only
945. // atomic within one filesystem, and /tmp is routinely a different one.
946. // The pid keeps two processes writing the same path off each other's temp
947. // file; the rename itself settles who wins the target.
948. const pid = linux.getpid();
949. const tmp = std.fmt.allocPrintSentinel(allocator, "{s}.hltmp{d}", .{ resolved, pid }, 0) catch
950. return api.makeError("fs.writeFile: out of memory");
951. defer allocator.free(tmp);
953. const rc = linuxOpenRc(tmp.ptr, .{ .ACCMODE = .WRONLY, .CREAT = true, .TRUNC = true }, mode);
954. if (rc < 0) return makeWriteError("fs.writeFile", path, @intCast(-rc));
955. const fd: i32 = @intCast(rc);
957. var wrote: usize = 0;
958. while (wrote < body.len) {
959. const n: isize = @bitCast(linux.write(fd, body.ptr + wrote, body.len - wrote));
960. if (n <= 0) {
961. _ = linux.close(fd);
962. _ = linux.unlink(tmp.ptr);
963. return makeWriteError("fs.writeFile", path, if (n < 0) @intCast(-n) else 5);
964. }
965. wrote += @intCast(n);
966. }
968. // fsync BEFORE the rename, or the rename can land while the bytes are
969. // still only in the page cache — a power cut then leaves an EMPTY file
970. // where a complete one used to be, which is worse than either outcome.
971. _ = linux.fsync(fd);
972. _ = linux.close(fd);
974. // O_CREAT honours the mode only through the umask; say it outright so a
975. // 0600 request is 0600 whatever the process umask happens to be.
976. _ = linux.chmod(tmp.ptr, mode);
978. const path_z = allocator.dupeZ(u8, resolved) catch return api.makeError("fs.writeFile: out of memory");
979. defer allocator.free(path_z);
980. const ren: isize = @bitCast(linux.rename(tmp.ptr, path_z.ptr));
981. if (ren < 0) {
982. _ = linux.unlink(tmp.ptr);
983. return makeWriteError("fs.writeFile", path, @intCast(-ren));
984. }
985. return api.makeBool(true);
986. }
988. const append_usage = "fs.appendFile expects (String path, String or Bytes contents, Number mode?)";
990. export fn hl_fs_append_file(argc: u32, argv: [*]const HlValue) callconv(.c) HlValue {
991. if (argc < 2 or argv[0].type != .hl_string or argv[1].type != .hl_string) {
992. return api.makeError(append_usage);
993. }
994. const path_str = argv[0].data.string;
995. const body_str = argv[1].data.string;
996. return appendWhole(path_str.ptr[0..path_str.len], body_str.ptr[0..body_str.len], modeArg(argc, argv));
997. }
999. /// hl_fs_append_file_hex(path, hex, mode?) — appendFile with a Bytes (ticket
1000. /// #88), the same hex-text crossing writeFile's hex sibling uses.
1001. export fn hl_fs_append_file_hex(argc: u32, argv: [*]const HlValue) callconv(.c) HlValue {
1002. if (argc < 2 or argv[0].type != .hl_string or argv[1].type != .hl_string) {
1003. return api.makeError(append_usage);
1004. }
1005. const path_str = argv[0].data.string;
1006. const hex = argv[1].data.string.ptr[0..argv[1].data.string.len];
1007. const raw = allocator.alloc(u8, hex.len / 2) catch return api.makeError("fs.appendFile: out of memory");
1008. defer allocator.free(raw);
1009. _ = std.fmt.hexToBytes(raw, hex) catch return api.makeError("fs.appendFile: not a Bytes");
1010. return appendWhole(path_str.ptr[0..path_str.len], raw, modeArg(argc, argv));
1011. }
1013. /// APPEND, NOT ATOMIC BY RENAME (writeFile's block comment above): an append
1014. /// MUTATES the file that is already there, so there is no whole "old" or
1015. /// "new" version to swap in — O_APPEND gives a narrower guarantee instead.
1016. /// The kernel positions a single write() at the file's CURRENT end and
1017. /// performs it as one operation, so two processes each appending a line never
1018. /// interleave their bytes mid-line and a reader never sees a torn append —
1019. /// which is why this is ONE write() of the whole body where writeFile's is
1020. /// (short-write retries aside). The file is created at `mode` (default 0600,
1021. /// same default as writeFile) if it is not there yet; O_APPEND on an existing
1022. /// file leaves its mode untouched, same as any other open of it.
1023. fn appendWhole(path: []const u8, body: []const u8, mode: u32) HlValue {
1024. const resolved = resolvePath(path) orelse return api.makeError("fs.appendFile: out of memory");
1025. defer allocator.free(resolved);
1026. const path_z = allocator.dupeZ(u8, resolved) catch return api.makeError("fs.appendFile: out of memory");
1027. defer allocator.free(path_z);
1029. const rc = linuxOpenRc(path_z.ptr, .{ .ACCMODE = .WRONLY, .CREAT = true, .APPEND = true }, mode);
1030. if (rc < 0) return makeWriteError("fs.appendFile", path, @intCast(-rc));
1031. const fd: i32 = @intCast(rc);
1032. defer _ = linux.close(fd);
1034. var wrote: usize = 0;
1035. while (wrote < body.len) {
1036. const n: isize = @bitCast(linux.write(fd, body.ptr + wrote, body.len - wrote));
1037. if (n <= 0) {
1038. return makeWriteError("fs.appendFile", path, if (n < 0) @intCast(-n) else 5);
1039. }
1040. wrote += @intCast(n);
1041. }
1042. return api.makeBool(true);
1043. }
1045. export fn hl_fs_remove(argc: u32, argv: [*]const HlValue) callconv(.c) HlValue {
1046. if (argc < 1 or argv[0].type != .hl_string) return api.makeError("fs.remove expects a string path");
1047. const path_str = argv[0].data.string;
1048. const path = path_str.ptr[0..path_str.len];
1050. const resolved = resolvePath(path) orelse return api.makeError("fs.remove: out of memory");
1051. defer allocator.free(resolved);
1052. const path_z = allocator.dupeZ(u8, resolved) catch return api.makeError("fs.remove: out of memory");
1053. defer allocator.free(path_z);
1055. const rc: isize = @bitCast(linux.unlink(path_z.ptr));
1056. if (rc < 0) {
1057. const errno: usize = @intCast(-rc);
1058. // ENOENT is success: the caller asked for the path to be gone.
1059. if (errno == 2) return api.makeBool(true);
1060. return makeWriteError("fs.remove", path, errno);
1061. }
1062. return api.makeBool(true);
1063. }