Skip to content

Lightpanda: the headless browser designed for AI and automation

24.5 KB
Raw Blame
// Copyright (C) 2023-2026  Lightpanda (Selecy SAS)
//
// Francis Bouvier <[email protected]>
// Pierre Tachoire <[email protected]>
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public License as
// published by the Free Software Foundation, either version 3 of the
// License, or (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU Affero General Public License for more details.
//
// You should have received a copy of the GNU Affero General Public License
// along with this program.  If not, see <https://www.gnu.org/licenses/>.
// https://w3c.github.io/webdriver-bidi/#type-script-RemoteValue

const std = @import("std");
const lp = @import("lightpanda");

const js = @import("../../browser/js/js.zig");
const Frame = @import("../../browser/Frame.zig");
const Node = @import("../../browser/webapi/Node.zig");
const Window = @import("../../browser/webapi/Window.zig");
const NodeList = @import("../../browser/webapi/collections/NodeList.zig");
const HTMLCollection = @import("../../browser/webapi/collections/HTMLCollection.zig");
const NodeRegistry = @import("../../NodeRegistry.zig");

const BiDi = @import("BiDi.zig");

const log = lp.log;
const Allocator = std.mem.Allocator;

pub const Remote = struct {
    body: Body,

    // Only set when the command asked for resultOwnership: "root".
    handle: ?[]const u8 = null,

    pub fn jsonStringify(self: *const Remote, w: anytype) error{WriteFailed}!void {
        try w.beginObject();

        try w.objectField("type");
        try w.write(self.body.typeName());

        switch (self.body) {
            .undefined, .null, .other => {},
            .boolean => |v| {
                try w.objectField("value");
                try w.write(v);
            },
            .string, .bigint, .date => |v| {
                try w.objectField("value");
                try w.write(v);
            },
            .regexp => |v| {
                try w.objectField("value");
                try w.write(v);
            },
            .number => |v| {
                try w.objectField("value");
                switch (v) {
                    .special => |s| try w.write(s),
                    .integer => |i| try w.write(i),
                    .float => |f| try w.write(f),
                }
            },
            .array, .nodelist, .htmlcollection => |items| {
                try w.objectField("value");
                try w.beginArray();
                for (items) |*item| {
                    try item.jsonStringify(w);
                }
                try w.endArray();
            },
            .object => |properties| {
                // An object's value is a list of [key, value] pairs, not a
                // JSON object: BiDi keys aren't necessarily strings.
                try w.objectField("value");
                try w.beginArray();
                for (properties) |*property| {
                    try w.beginArray();
                    try w.write(property.name);
                    try property.value.jsonStringify(w);
                    try w.endArray();
                }
                try w.endArray();
            },
            .node => |*v| try v.writeNode(w),
        }

        if (self.handle) |handle| {
            try w.objectField("handle");
            try w.write(handle);
        }

        try w.endObject();
    }

    const Body = union(enum) {
        undefined,
        null,
        boolean: bool,
        number: Number,
        string: []const u8,
        bigint: []const u8,
        date: []const u8,
        regexp: RegExp,
        array: []const Remote,
        nodelist: []const Remote,
        htmlcollection: []const Remote,
        object: []const Property,
        node: NodeValue,
        other: []const u8,

        fn typeName(self: *const Body) []const u8 {
            return switch (self.*) {
                .other => |name| name,
                else => @tagName(self.*),
            };
        }
    };
};

const Number = union(enum) {
    float: f64,
    integer: i64,
    special: enum { NaN, Infinity, @"-Infinity", @"-0" },

    fn from(value: f64) Number {
        if (std.math.isNan(value)) {
            return .{ .special = .NaN };
        }
        if (std.math.isPositiveInf(value)) {
            return .{ .special = .Infinity };
        }
        if (std.math.isNegativeInf(value)) {
            return .{ .special = .@"-Infinity" };
        }
        if (value == 0 and std.math.signbit(value)) {
            return .{ .special = .@"-0" };
        }

        const max_safe_integer = 9007199254740991;
        if (@trunc(value) == value and @abs(value) <= max_safe_integer) {
            // Whole numbers go out as JSON integers, avoids 5e0 for 5.0
            return .{ .integer = @intFromFloat(value) };
        }
        return .{ .float = value };
    }
};

pub const Property = struct {
    name: []const u8,
    value: Remote,
};

pub const RegExp = struct {
    flags: []const u8,
    pattern: []const u8,
};

pub const Attribute = struct {
    name: []const u8,
    value: []const u8,
};

const NodeValue = struct {
    node_type: u8,
    shared_id: []const u8,
    child_node_count: usize,
    local_name: ?[]const u8 = null,
    namespace_uri: ?[]const u8 = null,
    node_value: ?[]const u8 = null,
    attributes: ?[]const Attribute = null,
    children: ?[]const Remote = null,

    fn writeNode(node: *const NodeValue, w: anytype) error{WriteFailed}!void {
        try w.objectField("sharedId");
        try w.write(node.shared_id);

        try w.objectField("value");
        try w.beginObject();

        try w.objectField("nodeType");
        try w.write(node.node_type);

        try w.objectField("childNodeCount");
        try w.write(node.child_node_count);

        if (node.local_name) |v| {
            try w.objectField("localName");
            try w.write(v);
        }
        if (node.namespace_uri) |v| {
            try w.objectField("namespaceURI");
            try w.write(v);
        }
        if (node.node_value) |v| {
            try w.objectField("nodeValue");
            try w.write(v);
        }
        if (node.attributes) |attributes| {
            try w.objectField("attributes");
            try w.beginObject();
            for (attributes) |attribute| {
                try w.objectField(attribute.name);
                try w.write(attribute.value);
            }
            try w.endObject();
        }
        if (node.children) |children| {
            try w.objectField("children");
            try w.beginArray();
            for (children) |*child| {
                try child.jsonStringify(w);
            }
            try w.endArray();
        }

        try w.endObject();
    }
};

pub const Handles = struct {
    next_id: u32 = 1,
    allocator: Allocator,
    // id => global,the id is the handleId that client can send back
    map: std.AutoHashMapUnmanaged(u32, js.Value.Global) = .empty,

    pub fn deinit(self: *Handles) void {
        self.releaseAll();
        self.map.deinit(self.allocator);
    }

    pub fn releaseAll(self: *Handles) void {
        var it = self.map.valueIterator();
        while (it.next()) |global| {
            global.deinit();
        }
        self.map.clearRetainingCapacity();
    }

    pub fn add(self: *Handles, value: js.Value) !u32 {
        const global = try value.persist();
        errdefer global.deinit();

        const id = self.next_id;
        try self.map.putNoClobber(self.allocator, id, global);
        self.next_id = id + 1;
        return id;
    }

    pub fn get(self: *const Handles, id: u32) ?js.Value.Global {
        return self.map.get(id);
    }

    pub fn release(self: *Handles, id: u32) void {
        const entry = self.map.fetchRemove(id) orelse return;
        entry.value.deinit();
    }
};

// input parameter that we JSON parse
pub const SerializationOptions = struct {
    maxDomDepth: ?u32 = 0,
    maxObjectDepth: ?u32 = null,
    includeShadowTree: enum { none, open, all } = .none,

    pub fn options(self: *const SerializationOptions, own_root: bool) Serializer.Options {
        return .{
            .own_root = own_root,
            .max_dom_depth = self.maxDomDepth,
            .max_object_depth = self.maxObjectDepth,
        };
    }
};

pub const Serializer = struct {
    arena: Allocator,
    frame: *Frame,
    local: *const js.Local,
    registry: *NodeRegistry,
    handles: *Handles,
    opts: Options,

    // The containers we're currently inside, so a cycle collapses to the bare
    // type instead of recursing forever (maxObjectDepth defaults to unlimited).
    // Locals, not globals: everything happens inside the caller's scope.
    seen: std.ArrayList(js.Object) = .empty,

    pub const Options = struct {
        // by default, a node serializes without its children
        max_dom_depth: ?u32 = 0,

        // but an object serializes without limit (all the way down)
        max_object_depth: ?u32 = null,

        // when resultOwnership == "root", we'll persist the value in our handles lookup
        own_root: bool = false,
    };

    pub fn init(bidi: *BiDi, arena: Allocator, frame: *Frame, local: *const js.Local, opts: Options) Serializer {
        return .{
            .frame = frame,
            .local = local,
            .arena = arena,
            .handles = &bidi.handles,
            .registry = &bidi.node_registry,
            .opts = opts,
        };
    }

    pub fn run(self: *Serializer, value: js.Value) !Remote {
        return self.remote(value, 0, self.opts.own_root);
    }

    // A node reached without going through JS (browsingContext.locateNodes).
    pub fn domNode(self: *Serializer, dom_node: *Node) !Remote {
        return .{ .body = .{ .node = try self.node(dom_node, 0) } };
    }

    const Error = error{
        OutOfMemory,
        InvalidArgument,
        TypeError,
        JsException,
        ExecutionTerminated,
        MethodNotFound,
        DeadFunctionHandle,
        InvalidStringLength,
    };

    fn remote(self: *Serializer, value: js.Value, depth: u32, own: bool) Error!Remote {
        var handle_id: ?u32 = null;
        // The reply carries the handle; if serializing the body throws (a
        // throwing accessor, a Proxy trap) the client never learns it, so
        // don't keep the global alive.
        errdefer if (handle_id) |id| self.handles.release(id);

        // Symbols have identity, so the spec lets them carry a handle too.
        const handle: ?[]const u8 = if (own and (value.isObject() or value.isSymbol())) blk: {
            const id = try self.handles.add(value);
            handle_id = id;
            break :blk try self.arena.print("{d}", .{id});
        } else null;

        return .{ .handle = handle, .body = try self.body(value, depth) };
    }

    // Ordered by how often each comes back from a driver: primitives, then
    // nodes and arrays, with the exotics probed last so a plain object doesn't
    // pay for them.
    fn body(self: *Serializer, value: js.Value, depth: u32) !Remote.Body {
        if (value.isUndefined()) {
            return .undefined;
        }
        if (value.isString() != null) {
            return .{ .string = try value.toStringSliceWithAlloc(self.arena) };
        }
        if (value.isNumber()) {
            return .{ .number = .from(try value.toF64()) };
        }
        if (value.isBoolean()) {
            return .{ .boolean = value.toBool() };
        }
        if (value.isNull()) {
            return .null;
        }
        if (value.isBigInt()) {
            return .{ .bigint = try value.toStringSliceWithAlloc(self.arena) };
        }
        if (value.isSymbol()) {
            return .{ .other = "symbol" };
        }

        if (value.isObject() == false) {
            // Should not be possible, we've exhausted every primitive. But,
            // let's be defensive here.
            log.warn(.bidi, "unexpected value type", .{});
            return .{ .other = "object" };
        }

        if (value.taggedOpaque()) |tao| {
            return self.platform(tao, depth);
        }

        const object = value.toObject();
        if (value.isArray()) {
            if (self.isTooDeep(depth) or self.isSeen(object)) {
                return .{ .other = "array" };
            }
            return .{ .array = try self.items(value.toArray(), object, depth) };
        }

        if (value.isFunction()) {
            return .{ .other = "function" };
        }
        if (value.isPromise()) {
            return .{ .other = "promise" };
        }
        if (value.isNativeError()) {
            return .{ .other = "error" };
        }
        if (value.isDate()) {
            return .{ .date = try self.date(value) };
        }
        if (value.isRegExp()) {
            return .{ .regexp = .{
                .pattern = try (try object.get("source")).toStringSliceWithAlloc(self.arena),
                .flags = try (try object.get("flags")).toStringSliceWithAlloc(self.arena),
            } };
        }
        if (value.isTypedArray()) {
            return .{ .other = "typedarray" };
        }
        if (value.isArrayBuffer()) {
            return .{ .other = "arraybuffer" };
        }
        if (bareType(value)) |name| {
            return .{ .other = name };
        }

        if (self.isTooDeep(depth) or self.isSeen(object)) {
            return .{ .other = "object" };
        }
        return .{ .object = try self.properties(object, depth) };
    }

    // One of our objects. The spec only cares about four, the rest are opaque.
    fn platform(self: *Serializer, tao: js.TaggedOpaque, depth: u32) !Remote.Body {
        if (tao.as(Node)) |dom_node| {
            return .{ .node = try self.node(dom_node, 0) };
        }

        if (tao.as(Window)) |_| {
            return .{ .other = "window" };
        }

        if (tao.as(NodeList)) |list| {
            if (self.isTooDeep(depth)) {
                return .{ .other = "nodelist" };
            }
            const frame = self.frame;
            const nodes = try self.arena.alloc(Remote, try list.length(frame));
            for (nodes, 0..) |*item, i| {
                const dom_node = (try list.getAtIndex(i, frame)) orelse unreachable;
                item.* = .{ .body = .{ .node = try self.node(dom_node, 0) } };
            }
            return .{ .nodelist = nodes };
        }

        if (tao.as(HTMLCollection)) |collection| {
            if (self.isTooDeep(depth)) {
                return .{ .other = "htmlcollection" };
            }
            const frame = self.frame;
            const nodes = try self.arena.alloc(Remote, collection.length(frame));
            for (nodes, 0..) |*item, i| {
                const element = collection.getAtIndex(i, frame) orelse unreachable;
                item.* = .{ .body = .{ .node = try self.node(element.asNode(), 0) } };
            }
            return .{ .htmlcollection = nodes };
        }

        return .{ .other = "object" };
    }

    fn items(self: *Serializer, array: js.Array, object: js.Object, depth: u32) ![]const Remote {
        try self.see(object);
        defer self.unsee();

        const next_depth = depth + 1;
        const values = try self.arena.alloc(Remote, array.len());
        for (values, 0..) |*value, i| {
            value.* = try self.remote(try array.get(@intCast(i)), next_depth, false);
        }
        return values;
    }

    fn properties(self: *Serializer, object: js.Object, depth: u32) ![]const Property {
        try self.see(object);
        defer self.unsee();

        const next_depth = depth + 1;
        var it = try object.iterator();
        var list: std.ArrayList(Property) = try .initCapacity(self.arena, it.count);
        while (try it.next()) |entry| {
            list.appendAssumeCapacity(.{
                .name = try self.arena.dupe(u8, entry.name),
                .value = try self.remote(entry.value, next_depth, false),
            });
        }
        return list.items;
    }

    fn node(self: *Serializer, dom_node: *Node, dom_depth: u32) !NodeValue {
        const arena = self.arena;
        const registered = try self.registry.register(dom_node);

        var value: NodeValue = .{
            .shared_id = try arena.print("{d}", .{registered.id}),
            .node_type = dom_node.getNodeType(),
            .child_node_count = dom_node.getChildrenCount(),
        };

        if (dom_node.is(Node.Element)) |element| {
            value.local_name = element.getLocalName();
            value.namespace_uri = element.getNamespaceURI();

            const entries = element.attributeEntries();
            const attributes = try arena.alloc(Attribute, entries.len);
            for (entries, attributes) |*entry, *attribute| {
                attribute.* = .{ .name = entry.name(), .value = entry.value() };
            }
            value.attributes = attributes;
        } else if (dom_node.getNodeValue()) |node_value| {
            value.node_value = try arena.dupe(u8, node_value.str());
        }

        // Unlike maxObjectDepth, maxDomDepth counts down from the node being
        // serialized, so the default of 0 still yields the node's own
        // properties — just no children.
        const include_children = if (self.opts.max_dom_depth) |max| dom_depth < max else true;
        if (include_children) {
            var children: std.ArrayList(Remote) = .empty;
            var it = dom_node.childrenIterator();
            while (it.next()) |child| {
                try children.append(arena, .{ .body = .{ .node = try self.node(child, dom_depth + 1) } });
            }
            value.children = children.items;
        }

        return value;
    }

    fn date(self: *Serializer, value: js.Value) ![]const u8 {
        const ms = value.dateValue();
        if (std.math.isNan(ms)) {
            return "Invalid Date";
        }

        if (lp.datetime.DateTime.fromUnix(@intFromFloat(ms), .milliseconds)) |dt| {
            var buf: [28]u8 = undefined;
            var w: std.Io.Writer = .fixed(&buf);
            dt.formatMillis(&w) catch unreachable;
            return self.arena.dupe(u8, w.buffered());
        } else |_| {}

        const iso = try value.toObject().callMethod(js.Value, "toISOString", .{});
        return iso.toStringSliceWithAlloc(self.arena);
    }

    fn isSeen(self: *const Serializer, object: js.Object) bool {
        const candidate = object.toValue();
        for (self.seen.items) |ancestor| {
            if (ancestor.toValue().strictEquals(candidate)) {
                return true;
            }
        }
        return false;
    }

    fn see(self: *Serializer, object: js.Object) !void {
        try self.seen.append(self.arena, object);
    }

    fn unsee(self: *Serializer) void {
        _ = self.seen.pop();
    }

    fn isTooDeep(self: *const Serializer, depth: u32) bool {
        return depth >= (self.opts.max_object_depth orelse return false);
    }
};

// Some of these we should serialize fully, but we don't have anything that
// needs them right now.
fn bareType(value: js.Value) ?[]const u8 {
    if (value.isMap()) {
        return "map";
    }

    if (value.isSet()) {
        return "set";
    }

    if (value.isWeakMap()) {
        return "weakmap";
    }

    if (value.isWeakSet()) {
        return "weakset";
    }

    if (value.isProxy()) {
        return "proxy";
    }

    if (value.isGeneratorObject()) {
        return "generator";
    }

    return null;
}

// script.LocalValue -> JS, for callFunction's `arguments` and `this`.
pub fn toJs(
    local: *const js.Local,
    handles: *const Handles,
    registry: *const NodeRegistry,
    value: std.json.Value,
) !js.Value {
    const fields = switch (value) {
        .object => |o| o,
        else => return error.UnsupportedLocalValue,
    };

    if (fields.get("handle")) |handle| {
        const id = parseId(u32, handle) orelse return error.NoSuchHandle;
        const global = handles.get(id) orelse return error.NoSuchHandle;
        return global.local(local);
    }

    if (fields.get("sharedId")) |shared_id| {
        const node = try nodeFromSharedId(registry, shared_id);
        return local.zigValueToJs(node, .{});
    }

    const name = switch (fields.get("type") orelse return error.UnsupportedLocalValue) {
        .string => |s| s,
        else => return error.UnsupportedLocalValue,
    };
    const tag = std.meta.stringToEnum(enum {
        undefined,
        null,
        string,
        number,
        boolean,
        bigint,
        array,
        object,
    }, name) orelse return error.UnsupportedLocalValue;

    const payload = fields.get("value") orelse .null;
    switch (tag) {
        .undefined => return local.zigValueToJs({}, .{}),
        .null => return local.zigValueToJs(null, .{}),
        .string => return local.zigValueToJs(switch (payload) {
            .string => |s| s,
            else => return error.UnsupportedLocalValue,
        }, .{}),
        .boolean => return local.zigValueToJs(switch (payload) {
            .bool => |b| b,
            else => return error.UnsupportedLocalValue,
        }, .{}),
        .number => return local.newNumber(switch (payload) {
            .integer => |i| @floatFromInt(i),
            .float => |f| f,
            .string => |s| specialNumber(s) orelse return error.UnsupportedLocalValue,
            else => return error.UnsupportedLocalValue,
        }),
        // A bigint's value is its decimal digits as a string.
        .bigint => {
            const digits = switch (payload) {
                .string => |s| s,
                else => return error.UnsupportedLocalValue,
            };
            return local.newBigInt(digits) catch return error.UnsupportedLocalValue;
        },
        .array => {
            const entries = switch (payload) {
                .array => |a| a.items,
                else => return error.UnsupportedLocalValue,
            };
            var array = local.newArray(@intCast(entries.len));
            for (entries, 0..) |entry, i| {
                const item = try toJs(local, handles, registry, entry);
                if (try array.set(@intCast(i), item, .{}) == false) {
                    return error.UnsupportedLocalValue;
                }
            }
            return array.toValue();
        },
        // An object's value is a list of [key, value] pairs.
        .object => {
            const entries = switch (payload) {
                .array => |a| a.items,
                else => return error.UnsupportedLocalValue,
            };
            const object = local.newObject();
            for (entries) |entry| {
                const pair = switch (entry) {
                    .array => |p| p.items,
                    else => return error.UnsupportedLocalValue,
                };
                if (pair.len != 2) {
                    return error.UnsupportedLocalValue;
                }
                const key = objectKey(pair[0]) orelse return error.UnsupportedLocalValue;
                const item = try toJs(local, handles, registry, pair[1]);
                if (try object.set(key, item, .{}) == false) {
                    return error.UnsupportedLocalValue;
                }
            }
            return object.toValue();
        },
    }
}

fn objectKey(value: std.json.Value) ?[]const u8 {
    switch (value) {
        .string => |s| return s,
        .object => |fields| {
            // {"type": "string", "value": "over 9000"}  is supported
            const name = switch (fields.get("type") orelse return null) {
                .string => |s| s,
                else => return null,
            };
            if (std.mem.eql(u8, name, "string") == false) {
                return null;
            }
            return switch (fields.get("value") orelse return null) {
                .string => |s| s,
                else => null,
            };
        },
        else => return null,
    }
}

pub fn nodeFromSharedId(registry: *const NodeRegistry, shared_id: std.json.Value) error{NoSuchNode}!*Node {
    const id = parseId(NodeRegistry.Id, shared_id) orelse return error.NoSuchNode;
    const node = registry.lookup_by_id.get(id) orelse return error.NoSuchNode;
    return node.dom;
}

fn parseId(comptime T: type, value: std.json.Value) ?T {
    const str = switch (value) {
        .string => |s| s,
        else => return null,
    };
    return std.fmt.parseInt(T, str, 10) catch null;
}

fn specialNumber(name: []const u8) ?f64 {
    if (std.mem.eql(u8, name, "NaN")) {
        return std.math.nan(f64);
    }

    if (std.mem.eql(u8, name, "Infinity")) {
        return std.math.inf(f64);
    }

    if (std.mem.eql(u8, name, "-Infinity")) {
        return -std.math.inf(f64);
    }

    if (std.mem.eql(u8, name, "-0")) {
        return -0.0;
    }

    return null;
}