|
| 1 | +// SPDX-License-Identifier: Apache-2.0 |
| 2 | +// Original RFC 7464 (application/json-seq) reader over the shared stream input. |
| 3 | +import JSON |
| 4 | +/// A pull reader for RFC 7464 JSON text sequences (`application/json-seq`). |
| 5 | +/// |
| 6 | +/// Each text starts with the record separator byte (RS, `0x1E`) and runs to the |
| 7 | +/// next RS or the end of input. Consecutive RS bytes are not empty texts. Each text |
| 8 | +/// is parsed by the strict UTF-8 grammar, so surrounding whitespace, including the |
| 9 | +/// LF that writers append, is allowed. |
| 10 | +/// |
| 11 | +/// A text that is a top-level number, `true`, `false` or `null` must end in |
| 12 | +/// whitespace; otherwise it may have been truncated and is malformed (RFC 7464 |
| 13 | +/// section 2.4). Bytes before the first RS are a malformed text too. Malformed |
| 14 | +/// texts end the sequence by default; ``JSONTextSequenceOptions/MalformedTexts/skip`` |
| 15 | +/// continues with the next text instead. |
| 16 | +/// |
| 17 | +/// Failures report the absolute byte offset, the one-based text number as `record`, |
| 18 | +/// and the line and column within the text. |
| 19 | +public struct JSONTextSequence<Source: AsyncSequence>: AsyncSequence where Source.Element == JSONByteChunk { |
| 20 | + /// Each complete JSON text, in order. |
| 21 | + public typealias Element = JSON |
| 22 | + let source: Source |
| 23 | + let options: JSONTextSequenceOptions |
| 24 | + /// Wraps a caller-owned source of `application/json-seq` bytes. |
| 25 | + /// |
| 26 | + /// - Parameters: |
| 27 | + /// - source: The caller-owned asynchronous source of owned UTF-8 chunks. |
| 28 | + /// - options: Limits and the malformed-text policy. |
| 29 | + public init(_ source: Source, options: JSONTextSequenceOptions = .init()) { self.source = source; self.options = options } |
| 30 | + /// Creates an independent iterator with exclusive mutable state and no prefetch task. |
| 31 | + public func makeAsyncIterator() -> Iterator { .init(source: source.makeAsyncIterator(), options: options) } |
| 32 | + /// Exclusive pull iterator; never call next concurrently. |
| 33 | + /// |
| 34 | + /// Each iterator owns its budget and parsing state. Conditional Sendable of the |
| 35 | + /// sequence does not make this mutable iterator safe for concurrent access. |
| 36 | + public struct Iterator: AsyncIteratorProtocol { |
| 37 | + private var source: Source.AsyncIterator? |
| 38 | + private let options: JSONTextSequenceOptions |
| 39 | + private var driver: JSONTextSequenceDriver<Source.AsyncIterator>? |
| 40 | + fileprivate init(source: Source.AsyncIterator, options: JSONTextSequenceOptions) { self.source = source; self.options = options } |
| 41 | + /// The number of malformed texts skipped so far; always zero with the `fail` policy. |
| 42 | + public var skippedTexts: Int { driver?.skipped ?? 0 } |
| 43 | + /// Pulls at most one value through exclusively owned iterator state. |
| 44 | + /// |
| 45 | + /// An error or cancellation makes an initialized iterator terminal and prevents later pulls. |
| 46 | + /// - Returns: The next JSON text's value, or nil at the end of input. |
| 47 | + /// - Throws: Source, syntax or resource errors, or cancellation. |
| 48 | + public mutating func next() async throws -> JSON? { |
| 49 | + if driver == nil { driver = try JSONTextSequenceDriver(upstream: source!, options: options); source = nil } |
| 50 | + return try await driver!.next() |
| 51 | + } |
| 52 | + } |
| 53 | +} |
| 54 | +extension JSONTextSequence: Sendable where Source: Sendable {} |
| 55 | + |
| 56 | +private final class JSONTextSequenceDriver<Upstream: AsyncIteratorProtocol> where Upstream.Element == JSONByteChunk { |
| 57 | + static var separator: UInt8 { 0x1E } |
| 58 | + let input: JSONStreamInput<Upstream> |
| 59 | + let skipMalformed: Bool |
| 60 | + var terminal = false, resetOnNext = false, afterSeparator = false |
| 61 | + var offset: UInt64 = 0, texts: UInt64 = 0 |
| 62 | + var skipped = 0 |
| 63 | + init(upstream: Upstream, options: JSONTextSequenceOptions) throws { |
| 64 | + input = try JSONStreamInput(upstream: upstream, limits: options.limits); skipMalformed = options.malformedTexts == .skip |
| 65 | + } |
| 66 | + func next() async throws -> JSON? { |
| 67 | + guard !terminal else { return nil } |
| 68 | + do { |
| 69 | + try input.meter.checkpoint(); try input.meter.require(.pendingValues, 1) |
| 70 | + while true { |
| 71 | + if resetOnNext { try input.resetRecord(); resetOnNext = false } |
| 72 | + let introduced = afterSeparator, start = offset |
| 73 | + var text: [UInt8] = [], ended = false |
| 74 | + while true { |
| 75 | + guard try await input.ensureBytes() else { ended = true; break } |
| 76 | + let byte = input.bytes[input.index]; input.index += 1; offset += 1 |
| 77 | + try input.meter.work() |
| 78 | + if byte == Self.separator { break } |
| 79 | + try input.meter.require(.inputBytes, UInt64(text.count) + 1); try input.meter.retain(1); text.append(byte) |
| 80 | + } |
| 81 | + afterSeparator = !ended |
| 82 | + // Empty segments: input that starts with RS, consecutive RS bytes, or a final RS. |
| 83 | + if text.isEmpty { |
| 84 | + if ended { terminal = true; return nil } |
| 85 | + continue |
| 86 | + } |
| 87 | + texts += 1; resetOnNext = true |
| 88 | + do { |
| 89 | + let value = try parse(text, introduced: introduced) |
| 90 | + try input.meter.charge(.totalRecords) |
| 91 | + if ended { terminal = true } |
| 92 | + return value |
| 93 | + } catch let failure as JSONFailure { |
| 94 | + let relative = failure.location?.byteOffset ?? 0 |
| 95 | + let located = JSONFailure(failure.category, code: failure.code, |
| 96 | + location: .init(byteOffset: start + relative, line: failure.location?.line, |
| 97 | + column: failure.location?.column, record: texts), |
| 98 | + resource: failure.resource) |
| 99 | + guard skipMalformed, failure.category == .syntax else { throw located } |
| 100 | + try input.meter.charge(.totalRecords); skipped += 1 |
| 101 | + if ended { terminal = true; return nil } |
| 102 | + } |
| 103 | + } |
| 104 | + } catch { terminal = true; input.failed = true; throw error } |
| 105 | + } |
| 106 | + /// Parses one text; a missing leading RS or a possibly truncated scalar is a syntax failure. |
| 107 | + private func parse(_ text: [UInt8], introduced: Bool) throws -> JSON { |
| 108 | + guard introduced else { throw JSONFailure(.syntax, code: .invalidSyntax, location: .init(byteOffset: 0, line: 1, column: 1)) } |
| 109 | + let value = try JSONParser().parse(text, meter: &input.meter) |
| 110 | + switch value { |
| 111 | + case .object, .array, .string: return value |
| 112 | + default: |
| 113 | + // RFC 7464 section 2.4: a top-level scalar without trailing whitespace may be truncated. |
| 114 | + guard let last = text.last, last == 0x20 || last == 0x09 || last == 0x0A || last == 0x0D else { |
| 115 | + throw JSONFailure(.syntax, code: .unexpectedEOF, location: .init(byteOffset: UInt64(text.count))) |
| 116 | + } |
| 117 | + return value |
| 118 | + } |
| 119 | + } |
| 120 | +} |
0 commit comments