diff options
| author | Can Celik <ogulcancelik@gmail.com> | 2026-09-10 21:51:57 +0300 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2026-09-10 21:51:57 +0300 |
| commit | 425c86179791cd32e2d4ce0ae7f269940b4b0663 (patch) | |
| tree | e52c4383a6d69216cbe2a32638bf90841d7e2189 /vendor/libghostty-vt/src/terminal/snapshot/continuation.zig | |
| parent | 90e947a6e26e02f10ec7f1694c4eb5b78a86406b (diff) | |
chore: upgrade libghostty and preserve terminal behavior (#3906)
Diffstat (limited to 'vendor/libghostty-vt/src/terminal/snapshot/continuation.zig')
| -rw-r--r-- | vendor/libghostty-vt/src/terminal/snapshot/continuation.zig | 320 |
1 files changed, 320 insertions, 0 deletions
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/continuation.zig b/vendor/libghostty-vt/src/terminal/snapshot/continuation.zig new file mode 100644 index 00000000..92b52da0 --- /dev/null +++ b/vendor/libghostty-vt/src/terminal/snapshot/continuation.zig @@ -0,0 +1,320 @@ +//! Continuation record type. +//! +//! Continuation uses the standard record header. All trailing bytes +//! are payload bytes for the continuation state. +//! +//! A continuation's payload must be the minimal bytes to go from +//! a ground state to a non-ground state in a VT emulator. Any extra +//! bytes are treated as a validation error. + +const std = @import("std"); +const Allocator = std.mem.Allocator; +const record = @import("record.zig"); +const stream_continuation = @import("../stream_continuation.zig"); +const test_fixture = @import("fixture.zig"); + +/// A borrowed continuation value supplied to encode, or an allocator-owned +/// value stored in a decoded complete snapshot. +pub const Value = union(enum) { + /// Neither the VT parser nor UTF-8 decoder has unfinished state. + ground, + + /// Canonical replay-safe PTY bytes. Empty is equivalent to `ground`. + bytes: []const u8, +}; + +pub const ValidateError = stream_continuation.ValidateError || error{ + /// The common record's u32 payload length cannot represent these bytes. + Overflow, +}; + +/// Validate a continuation before any snapshot bytes are emitted. +pub fn validate(value: Value) ValidateError!void { + switch (value) { + .ground => {}, + .bytes => |bytes| { + if (std.math.cast(u32, bytes.len) == null) { + return error.Overflow; + } + try stream_continuation.validate(bytes); + }, + } +} + +pub const EncodeError = ValidateError || record.Writer.FinishError; + +/// Encode one complete CONTINUATION record. +pub fn encode( + value: Value, + stream: *record.Writer, +) EncodeError!void { + try validate(value); + + const payload = stream.begin(.continuation); + errdefer stream.cancel(); + switch (value) { + .ground => {}, + .bytes => |bytes| try payload.writeAll(bytes), + } + try stream.finish(); +} + +pub const DecodeError = Allocator.Error || + stream_continuation.ValidateError || + record.Reader.InitError || + record.Reader.FinishError || + std.Io.Reader.Error || + error{ + /// The next record is valid but is not CONTINUATION. + UnexpectedRecordTag, + + /// The declared payload exceeds caller policy. + ContinuationLimitExceeded, + }; + +/// Decode and validate one CONTINUATION record. +/// +/// A zero-length payload returns `ground` without allocating. A nonempty +/// payload returns allocator-owned bytes; although `Value.bytes` is a const +/// slice, the caller must eventually free it with the same allocator. +pub fn decode( + alloc: Allocator, + source: *std.Io.Reader, + max_bytes: usize, +) DecodeError!Value { + var record_reader: record.Reader = undefined; + try record_reader.init(source); + if (record_reader.header.tag != .continuation) { + return error.UnexpectedRecordTag; + } + + // Validate the header payload vs our max size since the header + // enforces it. + const len: usize = record_reader.header.payload_len; + if (len > max_bytes) return error.ContinuationLimitExceeded; + + if (len == 0) { + // Empty is the ground representation, but finish is still required: + // its CRC covers the tag and zero length even though there is no body. + try record_reader.finish(); + return .ground; + } + + // Consume the bytes + const bytes = try alloc.alloc(u8, len); + errdefer alloc.free(bytes); + try record_reader.payloadReader().readSliceAll(bytes); + try record_reader.finish(); + + // Framing is valid, so it is now safe to classify the bytes as replay + // state. Validation requires a minimal, unfinished, side-effect-free tail. + try stream_continuation.validate(bytes); + + // Ownership transfers to the returned Value only after all validation. + return .{ .bytes = bytes }; +} + +const test_ground_fixture = test_fixture.parse(@embedFile("testdata/continuation-ground-v1.hex")); +const test_utf8_fixture = test_fixture.parse(@embedFile("testdata/continuation-utf8-v1.hex")); +const test_esc_fixture = test_fixture.parse(@embedFile("testdata/continuation-esc-v1.hex")); +const test_csi_fixture = test_fixture.parse(@embedFile("testdata/continuation-csi-v1.hex")); +const test_osc_fixture = test_fixture.parse(@embedFile("testdata/continuation-osc-v1.hex")); +const test_dcs_fixture = test_fixture.parse(@embedFile("testdata/continuation-dcs-v1.hex")); +const test_apc_fixture = test_fixture.parse(@embedFile("testdata/continuation-apc-v1.hex")); + +test "continuation golden records" { + const Golden = struct { + path: []const u8, + candidate: []const u8, + value: Value, + expected: []const u8, + }; + const values = [_]Golden{ + .{ + .path = "src/terminal/snapshot/testdata/continuation-ground-v1.hex", + .candidate = "snapshot_fixture-continuation-ground-v1.hex", + .value = .ground, + .expected = &test_ground_fixture, + }, + .{ + .path = "src/terminal/snapshot/testdata/continuation-utf8-v1.hex", + .candidate = "snapshot_fixture-continuation-utf8-v1.hex", + .value = .{ .bytes = "\xF0\x9F\x98" }, + .expected = &test_utf8_fixture, + }, + .{ + .path = "src/terminal/snapshot/testdata/continuation-esc-v1.hex", + .candidate = "snapshot_fixture-continuation-esc-v1.hex", + .value = .{ .bytes = "\x1b" }, + .expected = &test_esc_fixture, + }, + .{ + .path = "src/terminal/snapshot/testdata/continuation-csi-v1.hex", + .candidate = "snapshot_fixture-continuation-csi-v1.hex", + .value = .{ .bytes = "\x1b[31" }, + .expected = &test_csi_fixture, + }, + .{ + .path = "src/terminal/snapshot/testdata/continuation-osc-v1.hex", + .candidate = "snapshot_fixture-continuation-osc-v1.hex", + .value = .{ .bytes = "\x1b]2;title" }, + .expected = &test_osc_fixture, + }, + .{ + .path = "src/terminal/snapshot/testdata/continuation-dcs-v1.hex", + .candidate = "snapshot_fixture-continuation-dcs-v1.hex", + .value = .{ .bytes = "\x1bPqdata" }, + .expected = &test_dcs_fixture, + }, + .{ + .path = "src/terminal/snapshot/testdata/continuation-apc-v1.hex", + .candidate = "snapshot_fixture-continuation-apc-v1.hex", + .value = .{ .bytes = "\x1b_Gdata" }, + .expected = &test_apc_fixture, + }, + }; + + for (values) |golden| { + var encoded: std.Io.Writer.Allocating = .init(std.testing.allocator); + defer encoded.deinit(); + var stream: record.Writer = .init( + std.testing.allocator, + &encoded.writer, + ); + defer stream.deinit(); + try encode(golden.value, &stream); + try test_fixture.expectEqual( + .bytes, + golden.path, + golden.candidate, + golden.expected, + encoded.written(), + ); + } +} + +test "continuation validates supported unfinished states" { + const values = [_][]const u8{ + "\x1b", + "\x1b[31", + "\x1b]2;title", + "\x1bPqdata", + "\x1b_Gdata", + "\xF0\x9F\x98", + }; + for (values) |bytes| try validate(.{ .bytes = bytes }); +} + +test "empty continuation bytes encode and decode as ground" { + const testing = std.testing; + try validate(.{ .bytes = "" }); + + var encoded: std.Io.Writer.Allocating = .init(testing.allocator); + defer encoded.deinit(); + var stream: record.Writer = .init(testing.allocator, &encoded.writer); + defer stream.deinit(); + try encode(.{ .bytes = "" }, &stream); + try testing.expectEqualStrings(&test_ground_fixture, encoded.written()); + + var source: std.Io.Reader = .fixed(encoded.written()); + const decoded = try decode(testing.allocator, &source, 0); + try testing.expect(decoded == .ground); +} + +test "continuation rejects invalid semantic shapes" { + const testing = std.testing; + try testing.expectError( + error.NoPendingState, + validate(.{ .bytes = "\x1b[31m" }), + ); + try testing.expectError( + error.ReplayWouldCommit, + validate(.{ .bytes = "\x1b[31\x07" }), + ); + try testing.expectError( + error.NonCanonicalContinuation, + validate(.{ .bytes = "prefix\x1b[31" }), + ); + try testing.expectError( + error.NonCanonicalContinuation, + validate(.{ .bytes = "\x1b[31\x1b[4" }), + ); +} + +test "continuation record round trip and cap" { + const testing = std.testing; + const values = [_]Value{ + .ground, + .{ .bytes = "\x1b[31" }, + .{ .bytes = "\xF0\x9F" }, + }; + + for (values) |value| { + var encoded: std.Io.Writer.Allocating = .init(testing.allocator); + defer encoded.deinit(); + var stream: record.Writer = .init(testing.allocator, &encoded.writer); + defer stream.deinit(); + try encode(value, &stream); + + var source: std.Io.Reader = .fixed(encoded.written()); + const decoded = try decode(testing.allocator, &source, 1024); + defer switch (decoded) { + .ground => {}, + .bytes => |bytes| testing.allocator.free(bytes), + }; + switch (value) { + .ground => try testing.expect(decoded == .ground), + .bytes => |expected| try testing.expectEqualStrings( + expected, + decoded.bytes, + ), + } + } + + var encoded: std.Io.Writer.Allocating = .init(testing.allocator); + defer encoded.deinit(); + var stream: record.Writer = .init(testing.allocator, &encoded.writer); + defer stream.deinit(); + try encode(.{ .bytes = "\x1b[31" }, &stream); + + var capped_source: std.Io.Reader = .fixed(encoded.written()); + var failing = testing.FailingAllocator.init(testing.allocator, .{ + .fail_index = 0, + }); + try testing.expectError( + error.ContinuationLimitExceeded, + decode(failing.allocator(), &capped_source, 3), + ); + try testing.expectEqual( + @as(usize, record.Header.len), + capped_source.seek, + ); +} + +test "continuation record rejects truncation, checksum, and tag" { + const testing = std.testing; + + for (0..test_csi_fixture.len) |len| { + var source: std.Io.Reader = .fixed(test_csi_fixture[0..len]); + try testing.expectError( + error.EndOfStream, + decode(testing.allocator, &source, 1024), + ); + } + + var invalid_checksum = test_csi_fixture; + invalid_checksum[6] ^= 1; + var checksum_source: std.Io.Reader = .fixed(&invalid_checksum); + try testing.expectError( + error.InvalidChecksum, + decode(testing.allocator, &checksum_source, 1024), + ); + + var wrong_tag = test_ground_fixture; + std.mem.writeInt(u16, wrong_tag[0..2], @intFromEnum(record.Tag.ready), .little); + var tag_source: std.Io.Reader = .fixed(&wrong_tag); + try testing.expectError( + error.UnexpectedRecordTag, + decode(testing.allocator, &tag_source, 1024), + ); +} |
