tickets

20.6 KB

1. // hl:mpackdb plugin — native shared library (mission 066)
2. // Zig port of mpackdb v1.0.7 (MessagePack DB with binary-search indexes).
3. //
4. // Layout:
5. // msgpack.zig — MessagePack codec (msgpackr-compatible, see D12)
6. // engine.zig — DB engine (MPackDB/IndexManager semantics)
7. // mpackdb.zig — this file: plugin ABI surface
8. //
9. // Exports:
10. // hl_mpackdb_open(path, primaryKey, indexes, compact) → handle
11. // handle ops: insert(record) / find_all() / find_pk(v) /
12. // find_index(field, v) / find_range(field, from, to) /
13. // delete_pk(v) / update_pk(v, record) / count() /
14. // compact() / persist() / last_error() / pk_name()
15. //
16. // The `hl:mpackdb` .hl surface (MPackDB.hl, cursor.hl, server.hl) is the public
17. // API; these ops are its transport.
18. //
19. // Cursors materialize matches eagerly into a per-iterator arena; the runtime
20. // deep-copies each record on next(), and the arena is freed at iterator deinit.
22. const std = @import("std");
23. const api = @import("plugin_api");
24. pub const msgpack = @import("msgpack.zig");
25. pub const engine = @import("engine.zig");
27. const HlValue = api.HlValue;
28. const HlObject = api.HlObject;
29. const HlField = api.HlField;
30. const HlIterator = api.HlIterator;
31. const HlHandle = api.HlHandle;
32. const HlString = api.HlString;
34. var gpa_state = std.heap.DebugAllocator(.{}){};
35. const gpa = gpa_state.allocator();
37. fn hlStr(comptime s: []const u8) HlString {
38. return .{ .ptr = s.ptr, .len = s.len };
39. }
41. // =========================================================================
42. // Path resolution (mission 077, 074 GAP 9)
43. //
44. // CONTRACT — the same one hl:fs got in mission 068: a relative db path resolves
45. // against the MAIN SCRIPT's directory, not the process CWD. `cd /tmp && hybriel
46. // /srv/app/main.hl` must find /srv/app's database, not create a second one in
47. // /tmp. Absolute paths are used as-is. The runtime injects the directory through
48. // the optional plugin hook hl_mpackdb_set_script_dir right after dlopen.
49. // =========================================================================
51. var script_dir: ?[]u8 = null;
53. export fn hl_mpackdb_set_script_dir(ptr: [*]const u8, len: usize) callconv(.c) void {
54. if (script_dir) |old| gpa.free(old);
55. script_dir = gpa.dupe(u8, ptr[0..len]) catch null;
56. }
58. /// Resolve a (possibly relative) db path against the script dir. The returned
59. /// slice is gpa-allocated; caller frees.
60. fn resolvePath(path: []const u8) ?[]u8 {
61. if (path.len == 0 or path[0] == '/') return gpa.dupe(u8, path) catch null;
62. if (script_dir) |sd| return std.fmt.allocPrint(gpa, "{s}/{s}", .{ sd, path }) catch null;
63. return gpa.dupe(u8, path) catch null;
64. }
66. // =========================================================================
67. // HlValue ⇄ msgpack.Value conversion
68. // =========================================================================
70. /// AN EMPTY LIST is marked by its `fields` address (ticket #58) — the runtime's
71. /// contract, stated in native/src/plugin_loader.zig beside the same constant. Zero
72. /// fields alone read back as an empty hybrid, and `tags = []` was stored as a map.
73. const EMPTY_LIST_FIELDS: [*]HlField = @ptrFromInt(0x4C49_5354_0000_0008);
75. fn isEmptyList(obj: *const HlObject) bool {
76. return obj.field_count == 0 and obj.fields == EMPTY_LIST_FIELDS;
77. }
79. /// Hybriel value (as HlObject tree) → msgpack value, allocated in `arena`.
80. /// An HlObject whose keys are exactly the sequence "0".."n-1" (in order)
81. /// becomes a msgpack array; everything else becomes a map. Hybriel null and
82. /// undefined both arrive as hl_null → msgpack nil.
83. fn hlToMsgpack(arena: std.mem.Allocator, v: HlValue) msgpack.Value {
84. switch (v.type) {
85. .hl_null => return .nil,
86. .hl_bool => return .{ .boolean = v.data.boolean },
87. .hl_number => return .{ .number = v.data.number },
88. .hl_string => {
89. const s = v.data.string.ptr[0..v.data.string.len];
90. const copy = arena.dupe(u8, s) catch return .nil;
91. return .{ .str = copy };
92. },
93. .hl_object => {
94. const obj = v.data.object;
95. const fields = obj.fields[0..obj.field_count];
96. // strict numeric sequence "0".."n-1" → array; an empty list carries its
97. // mark (ticket #58), or `tags = []` was stored as an empty map
98. var is_array = fields.len > 0 or isEmptyList(obj);
99. for (fields, 0..) |f, i| {
100. const k = f.key.ptr[0..f.key.len];
101. var buf: [20]u8 = undefined;
102. const expect = std.fmt.bufPrint(&buf, "{d}", .{i}) catch "";
103. if (!std.mem.eql(u8, k, expect)) {
104. is_array = false;
105. break;
106. }
107. }
108. if (is_array) {
109. const items = arena.alloc(msgpack.Value, fields.len) catch return .nil;
110. for (fields, 0..) |f, i| items[i] = hlToMsgpack(arena, f.value);
111. return .{ .array = items };
112. }
113. const entries = arena.alloc(msgpack.Entry, fields.len) catch return .nil;
114. for (fields, 0..) |f, i| {
115. const k = arena.dupe(u8, f.key.ptr[0..f.key.len]) catch return .nil;
116. entries[i] = .{ .key = .{ .str = k }, .value = hlToMsgpack(arena, f.value) };
117. }
118. return .{ .map = entries };
119. },
120. else => return .nil,
121. }
122. }
124. /// msgpack value → HlValue tree allocated in `arena` (no deinit hooks — the
125. /// runtime deep-copies immediately; the arena outlives the call).
126. fn msgpackToHl(arena: std.mem.Allocator, v: msgpack.Value) HlValue {
127. switch (v) {
128. .nil, .undef => return api.makeNull(),
129. .boolean => |b| return api.makeBool(b),
130. .number => |n| return api.makeNumber(n),
131. .str => |s| return api.makeString(s),
132. .bin => |b| return api.makeString(b),
133. .array => |items| {
134. const fields = arena.alloc(HlField, items.len) catch return api.makeNull();
135. for (items, 0..) |it, i| {
136. var buf: [20]u8 = undefined;
137. const k = std.fmt.bufPrint(&buf, "{d}", .{i}) catch "";
138. const key = arena.dupe(u8, k) catch return api.makeNull();
139. fields[i] = .{ .key = .{ .ptr = key.ptr, .len = key.len }, .value = msgpackToHl(arena, it) };
140. }
141. const obj = arena.create(HlObject) catch return api.makeNull();
142. obj.* = .{ .fields = if (items.len == 0) EMPTY_LIST_FIELDS else fields.ptr, .field_count = fields.len, .deinit_fn = null };
143. return api.makeObject(obj);
144. },
145. .map => |entries| {
146. const fields = arena.alloc(HlField, entries.len) catch return api.makeNull();
147. var n: usize = 0;
148. for (entries) |e| {
149. const key: []const u8 = switch (e.key) {
150. .str => |s| s,
151. .number => |num| blk: {
152. var buf: [40]u8 = undefined;
153. const k = engine.jsNumFmt(&buf, num);
154. break :blk arena.dupe(u8, k) catch continue;
155. },
156. else => continue,
157. };
158. fields[n] = .{ .key = .{ .ptr = key.ptr, .len = key.len }, .value = msgpackToHl(arena, e.value) };
159. n += 1;
160. }
161. const obj = arena.create(HlObject) catch return api.makeNull();
162. obj.* = .{ .fields = fields.ptr, .field_count = n, .deinit_fn = null };
163. return api.makeObject(obj);
164. },
165. .ext => {
166. if (v.timestampMs()) |ms| return api.makeNumber(ms);
167. return api.makeNull();
168. },
169. }
170. }
172. fn hlKey(v: HlValue) ?engine.Key {
173. return switch (v.type) {
174. .hl_number => .{ .num = v.data.number },
175. .hl_string => .{ .str = v.data.string.ptr[0..v.data.string.len] },
176. else => null,
177. };
178. }
180. // =========================================================================
181. // Record iterator (eagerly materialized)
182. // =========================================================================
184. const RecIterState = struct {
185. arena_state: std.heap.ArenaAllocator,
186. records: []msgpack.Value = &.{},
187. idx: usize = 0,
188. };
190. fn recIterNext(ctx: ?*anyopaque) callconv(.c) HlValue {
191. const state: *RecIterState = @ptrCast(@alignCast(ctx orelse return api.makeNull()));
192. if (state.idx >= state.records.len) return api.makeNull();
193. const v = state.records[state.idx];
194. state.idx += 1;
195. return msgpackToHl(state.arena_state.allocator(), v);
196. }
198. fn recIterDeinit(ctx: ?*anyopaque) callconv(.c) void {
199. const state: *RecIterState = @ptrCast(@alignCast(ctx orelse return));
200. state.arena_state.deinit();
201. gpa.destroy(state);
202. }
204. fn makeRecordIterator(records: []msgpack.Value, arena_state: std.heap.ArenaAllocator) HlValue {
205. const state = gpa.create(RecIterState) catch return api.makeNull();
206. state.* = .{ .arena_state = arena_state, .records = records };
207. const iter = gpa.create(HlIterator) catch {
208. gpa.destroy(state);
209. return api.makeNull();
210. };
211. iter.* = .{
212. .context = @ptrCast(state),
213. .next_fn = &recIterNext,
214. .deinit_fn = &recIterDeinitOuter,
215. };
216. return api.makeIterator(iter);
217. }
219. // The runtime's IterWrapper deinit calls iter.deinit_fn then frees its own
220. // wrapper — but the HlIterator struct itself is ours to free.
221. fn recIterDeinitOuter(ctx: ?*anyopaque) callconv(.c) void {
222. recIterDeinit(ctx);
223. }
225. // =========================================================================
226. // DB handle
227. // =========================================================================
229. const DbState = struct {
230. db: *engine.Db,
231. };
233. export fn hl_mpackdb_open(argc: u32, argv: [*]const HlValue) callconv(.c) HlValue {
234. if (argc < 1 or argv[0].type != .hl_string) return api.makeNull();
235. const raw_path = argv[0].data.string.ptr[0..argv[0].data.string.len];
236. // mission 077: script-relative, like every other path in Hybriel.
237. const path = resolvePath(raw_path) orelse return api.makeNull();
238. defer gpa.free(path);
240. var opts = engine.OpenOptions{};
241. if (argc > 1 and argv[1].type == .hl_string and argv[1].data.string.len > 0) {
242. opts.primary_key = argv[1].data.string.ptr[0..argv[1].data.string.len];
243. }
244. var index_names: [64][]const u8 = undefined;
245. var index_count: usize = 0;
246. if (argc > 2 and argv[2].type == .hl_object) {
247. const obj = argv[2].data.object;
248. for (obj.fields[0..obj.field_count]) |f| {
249. if (f.value.type != .hl_string) continue;
250. if (index_count >= index_names.len) break;
251. index_names[index_count] = f.value.data.string.ptr[0..f.value.data.string.len];
252. index_count += 1;
253. }
254. }
255. opts.indexes = index_names[0..index_count];
256. if (argc > 3 and argv[3].type == .hl_bool) {
257. opts.compact = argv[3].data.boolean;
258. }
260. const db = engine.Db.open(gpa, path, opts) catch |e| {
261. std.debug.print("mpackdb plugin: open failed: {s}\n", .{@errorName(e)});
262. return api.makeNull();
263. };
265. const state = gpa.create(DbState) catch {
266. db.close();
267. return api.makeNull();
268. };
269. state.* = .{ .db = db };
271. const handle = gpa.create(HlHandle) catch {
272. db.close();
273. gpa.destroy(state);
274. return api.makeNull();
275. };
276. handle.* = .{
277. .context = @ptrCast(state),
278. .call_fn = &handleCall,
279. .close_fn = &handleClose,
280. .type_name = hlStr("MPackDB"),
281. };
282. return api.makeHandle(handle);
283. }
285. fn errDeinit(val: *HlValue) callconv(.c) void {
286. if (val.type == .hl_error) {
287. const s = val.data.string;
288. gpa.free(@constCast(s.ptr[0..s.len]));
289. }
290. }
292. /// mission 077 (074 GAP 10): querying a field that carries no index is a
293. /// MISTAKE, not an empty result — mpackdb only answers through binary-searched
294. /// indexes, so `[]` was indistinguishable from "no such record" and hid the
295. /// missing declaration. The message names the field, the op and every index the
296. /// db was actually opened with (insertion order: primary key first).
297. fn makeNoIndexError(db: *engine.Db, op: []const u8, field: []const u8) HlValue {
298. var list: std.ArrayList(u8) = .empty;
299. defer list.deinit(gpa);
300. for (db.idx.keys()) |k| {
301. if (list.items.len > 0) list.appendSlice(gpa, ", ") catch {};
302. list.append(gpa, '\'') catch {};
303. list.appendSlice(gpa, k) catch {};
304. list.append(gpa, '\'') catch {};
305. }
306. const declared = if (list.items.len == 0) "none" else list.items;
307. const msg = std.fmt.allocPrint(
308. gpa,
309. "mpackdb.{s}: no index on field '{s}' — this db is indexed on [{s}]; every query goes through an index (declare it in `indexes` when opening, or query the primary key)",
310. .{ op, field, declared },
311. ) catch return api.makeError("mpackdb: no index on that field");
312. var v = api.makeError(msg);
313. v.deinit_fn = &errDeinit;
314. return v;
315. }
317. fn handleClose(ctx: ?*anyopaque) callconv(.c) void {
318. const state: *DbState = @ptrCast(@alignCast(ctx orelse return));
319. state.db.close();
320. gpa.destroy(state);
321. }
323. fn pkStringDeinit(val: *HlValue) callconv(.c) void {
324. if (val.type == .hl_string) {
325. const s = val.data.string;
326. gpa.free(@constCast(s.ptr[0..s.len]));
327. }
328. }
330. fn handleCall(ctx: ?*anyopaque, op: HlString, argc: u32, argv: [*]const HlValue) callconv(.c) HlValue {
331. const state: *DbState = @ptrCast(@alignCast(ctx orelse return api.makeNull()));
332. const db = state.db;
333. const method = op.ptr[0..op.len];
335. if (std.mem.eql(u8, method, "insert")) {
336. if (argc < 1 or argv[0].type != .hl_object) return api.makeNull();
337. var arena_state = std.heap.ArenaAllocator.init(gpa);
338. defer arena_state.deinit();
339. const arena = arena_state.allocator();
340. const rec = hlToMsgpack(arena, argv[0]);
341. if (rec != .map) return api.makeNull();
342. const res = db.insert(arena, rec, false) catch |e| {
343. if (e != error.DuplicateKey) {
344. std.debug.print("mpackdb plugin: insert failed: {s}\n", .{@errorName(e)});
345. db.last_error = std.fmt.bufPrint(&db.last_error_buf, "insert failed: {s}", .{@errorName(e)}) catch "insert failed";
346. }
347. return api.makeNull();
348. };
349. switch (res) {
350. .pk_num => |n| return api.makeNumber(n),
351. .pk_str => |s| {
352. const copy = gpa.dupe(u8, s) catch return api.makeNull();
353. var out = api.makeString(copy);
354. out.deinit_fn = &pkStringDeinit;
355. return out;
356. },
357. .record => return api.makeBool(true),
358. }
359. }
361. if (std.mem.eql(u8, method, "find_all")) {
362. var arena_state = std.heap.ArenaAllocator.init(gpa);
363. const arena = arena_state.allocator();
364. var records: std.ArrayList(msgpack.Value) = .empty;
365. db.refresh();
366. var scanner = engine.Db.Scanner.init(db, arena, true);
367. while (true) {
368. const maybe = scanner.next(arena) catch break;
369. const rec = maybe orelse break;
370. records.append(arena, rec.value) catch break;
371. }
372. scanner.deinit();
373. const slice = records.toOwnedSlice(arena) catch &.{};
374. return makeRecordIterator(@constCast(slice), arena_state);
375. }
377. if (std.mem.eql(u8, method, "find_pk")) {
378. if (argc < 1) return api.makeNull();
379. const key = hlKey(argv[0]) orelse return api.makeNull();
380. var arena_state = std.heap.ArenaAllocator.init(gpa);
381. const arena = arena_state.allocator();
382. var locs: std.ArrayList(engine.Loc) = .empty;
383. db.findPkLocs(arena, key, &locs) catch {
384. arena_state.deinit();
385. return api.makeNull();
386. };
387. return locsToIterator(db, arena_state, locs.items);
388. }
390. if (std.mem.eql(u8, method, "find_index")) {
391. if (argc < 2 or argv[0].type != .hl_string) return api.makeNull();
392. const field = argv[0].data.string.ptr[0..argv[0].data.string.len];
393. const key = hlKey(argv[1]) orelse return api.makeNull();
394. var arena_state = std.heap.ArenaAllocator.init(gpa);
395. const arena = arena_state.allocator();
396. var locs: std.ArrayList(engine.Loc) = .empty;
397. db.findIndexLocs(arena, field, key, &locs) catch |e| {
398. arena_state.deinit();
399. if (e == error.NoSuchIndex) return makeNoIndexError(db, "find", field);
400. return api.makeNull();
401. };
402. return locsToIterator(db, arena_state, locs.items);
403. }
405. if (std.mem.eql(u8, method, "find_range")) {
406. if (argc < 1 or argv[0].type != .hl_string) return api.makeNull();
407. const field = argv[0].data.string.ptr[0..argv[0].data.string.len];
408. const from: ?engine.Key = if (argc > 1) hlKey(argv[1]) else null;
409. const to: ?engine.Key = if (argc > 2) hlKey(argv[2]) else null;
410. var arena_state = std.heap.ArenaAllocator.init(gpa);
411. const arena = arena_state.allocator();
412. var locs: std.ArrayList(engine.Loc) = .empty;
413. db.findRangeLocs(arena, field, from, to, &locs) catch |e| {
414. arena_state.deinit();
415. if (e == error.NoSuchIndex) return makeNoIndexError(db, "range", field);
416. return api.makeNull();
417. };
418. return locsToIterator(db, arena_state, locs.items);
419. }
421. if (std.mem.eql(u8, method, "delete_pk")) {
422. if (argc < 1) return api.makeNull();
423. const key = hlKey(argv[0]) orelse return api.makeNull();
424. var arena_state = std.heap.ArenaAllocator.init(gpa);
425. defer arena_state.deinit();
426. const arena = arena_state.allocator();
427. var deleted: std.ArrayList(msgpack.Value) = .empty;
428. const n = db.deletePk(arena, key, &deleted) catch |e| {
429. std.debug.print("mpackdb plugin: delete failed: {s}\n", .{@errorName(e)});
430. return api.makeNull();
431. };
432. return api.makeNumber(@floatFromInt(n));
433. }
435. if (std.mem.eql(u8, method, "update_pk")) {
436. if (argc < 2 or argv[1].type != .hl_object) return api.makeNull();
437. const key = hlKey(argv[0]) orelse return api.makeNull();
438. var arena_state = std.heap.ArenaAllocator.init(gpa);
439. defer arena_state.deinit();
440. const arena = arena_state.allocator();
441. const rec = hlToMsgpack(arena, argv[1]);
442. if (rec != .map) return api.makeNull();
443. const n = db.updatePk(arena, key, rec) catch |e| {
444. if (e == error.RecordLacksPrimaryKey) {
445. db.last_error = std.fmt.bufPrint(&db.last_error_buf, "update refused: the record carries no '{s}' (update's record must carry the primary key)", .{db.pk orelse ""}) catch "update refused: the record carries no primary key";
446. return api.makeNull();
447. }
448. if (e != error.DuplicateKey) {
449. std.debug.print("mpackdb plugin: update failed: {s}\n", .{@errorName(e)});
450. }
451. return api.makeNull();
452. };
453. return api.makeNumber(@floatFromInt(n));
454. }
456. if (std.mem.eql(u8, method, "count")) {
457. var arena_state = std.heap.ArenaAllocator.init(gpa);
458. defer arena_state.deinit();
459. const arena = arena_state.allocator();
460. db.refresh();
461. var scanner = engine.Db.Scanner.init(db, arena, true);
462. defer scanner.deinit();
463. var n: usize = 0;
464. while (true) {
465. const maybe = scanner.next(arena) catch break;
466. if (maybe == null) break;
467. n += 1;
468. }
469. return api.makeNumber(@floatFromInt(n));
470. }
472. if (std.mem.eql(u8, method, "compact")) {
473. db.compact() catch |e| {
474. std.debug.print("mpackdb plugin: compact failed: {s}\n", .{@errorName(e)});
475. };
476. return api.makeNull();
477. }
479. if (std.mem.eql(u8, method, "persist")) {
480. db.persistNow() catch |e| {
481. std.debug.print("mpackdb plugin: persist failed: {s}\n", .{@errorName(e)});
482. };
483. return api.makeNull();
484. }
486. if (std.mem.eql(u8, method, "last_error")) {
487. return api.makeString(db.last_error);
488. }
490. // The primary key field name with its */@/! prefixes stripped — the .hl
491. // wrapper needs the bare name to route find(field, …) to find_pk.
492. if (std.mem.eql(u8, method, "pk_name")) {
493. const p = db.pk orelse return api.makeNull();
494. return api.makeString(p);
495. }
497. return api.makeNull();
498. }
500. /// Decode records at `locs` into the iterator arena and wrap them.
501. fn locsToIterator(db: *engine.Db, arena_state: std.heap.ArenaAllocator, locs: []const engine.Loc) HlValue {
502. var st = arena_state;
503. const arena = st.allocator();
504. var records: std.ArrayList(msgpack.Value) = .empty;
505. for (locs) |loc| {
506. const rec = db.readAt(arena, loc) catch continue;
507. records.append(arena, rec) catch break;
508. }
509. const slice = records.toOwnedSlice(arena) catch &.{};
510. return makeRecordIterator(@constCast(slice), st);
511. }
513. test {
514. _ = msgpack;
515. _ = engine;
516. }