// 流式行集:C 侧把结果按帧推进 pipe(布局见 `ffi/stream.c` 的 `mturso_stream_stmt_rows`),
// 这里从 `RawFdStream` **拉** —— 读一个、算一个,不物化。

///|
/// 拉取式行读取器(本版是**流式**实现:`has_next` 才去读下一帧)。
pub(open) trait Rows {
  async fn has_next(Self) -> Bool raise TursoError
  fn get_row(Self) -> Row raise TursoError
  fn columns(Self) -> Array[@value.Column]
  fn changes(Self) -> Int64
  /// 同步、不抛、幂等 —— 关掉读端就等于取消(worker 的 write 拿到 EPIPE 就停)。
  fn close(Self) -> Unit
}

///|
/// 流式行集。
pub struct ResultRows {
  stream : @raw_fd.RawFdStream
  columns : Array[@value.Column]
  stmt : @ffi.Stmt
  conn : @ffi.Conn
  priv sync_io : SyncIoContext?
  release : Connection?
  mut pending : Array[@value.Value]?
  mut pending_raw : Array[Bytes]?
  mut changes : Int64
  mut done : Bool
  mut closed : Bool
}

///|
pub impl Rows for ResultRows with fn has_next(self) {
  for ;; {
    if self.closed || self.done {
      return false
    }
    let (tag, payload) = read_frame(self.stream)
    match tag {
      0 => {
        self.done = true
        if payload.length() >= 8 {
          let rd : Rd = { b: payload, p: 0, }
          self.changes = rd.i64()
        }
        return false
      }
      2 => {
        let (values, raws) = parse_cells(payload, self.columns.length())
        self.pending = Some(values)
        self.pending_raw = Some(raws)
        return true
      }
      3 => {
        self.done = true
        raise stream_error(payload)
      }
      4 =>
        match self.sync_io {
          Some(io) => {
            io.process_one()
            @ffi.conn_resume_sync_io(self.conn)
            continue
          }
          None => {
            self.done = true
            raise TursoError::ConnectionError(
              "sync I/O requested by a local connection",
            )
          }
        }
      _ => {
        self.done = true
        raise TursoError::QueryError("unexpected frame tag \{tag}")
      }
    }
  }
}

///|
pub impl Rows for ResultRows with fn get_row(self) {
  match self.pending {
    Some(values) => {
      self.pending = None
      let raws = match self.pending_raw {
        Some(r) => r
        None => []
      }
      self.pending_raw = None
      { values, columns: self.columns, raw: raws, }
    }
    None =>
      raise TursoError::QueryError("no pending row; call has_next() first")
  }
}

///|
pub impl Rows for ResultRows with fn columns(self) {
  self.columns
}

///|
pub impl Rows for ResultRows with fn changes(self) {
  self.changes
}

///|
pub impl Rows for ResultRows with fn close(self) {
  if !self.closed {
    self.closed = true
    // 关掉读端:worker 的 write 会拿到 EPIPE,立刻停下(这就是取消)
    self.stream.close()
    @ffi.conn_resume_sync_io(self.conn)
    // 等 worker 真的停了,之后 stmt 才能安全释放
    @ffi.conn_wait_job(self.conn)
    // 池上发起的查询:读完把连接还回池
    match self.release {
      Some(c) => c.close()
      None => ()
    }
  }
}

///|
/// 让具体类型上的 `rows.has_next()` 这类 dot 调用也成立(不只是 `&Rows`)。
pub extend ResultRows with Rows::{has_next, get_row, columns, changes, close}

// ---------------------------------------------------------------------------
// 二进制读游标(小端)
// ---------------------------------------------------------------------------

///|
priv struct Rd {
  b : Bytes
  mut p : Int
}

///|
fn Rd::u8(self : Rd) -> Int raise TursoError {
  if self.p >= self.b.length() {
    raise TursoError::QueryError("truncated result buffer")
  }
  let v = self.b[self.p].to_int()
  self.p = self.p + 1
  v
}

///|
fn Rd::u32(self : Rd) -> Int raise TursoError {
  let mut v = 0
  for i in 0..<4 {
    v = v | (self.u8() << (8 * i))
  }
  v
}

///|
fn Rd::i64(self : Rd) -> Int64 raise TursoError {
  let mut v = 0L
  for i in 0..<8 {
    v = v | (self.u8().to_int64() << (8 * i))
  }
  v
}

///|
fn Rd::f64(self : Rd) -> Double raise TursoError {
  self.i64().reinterpret_as_double()
}

///|
fn Rd::bytes(self : Rd) -> Bytes raise TursoError {
  let n = self.u32()
  if self.p + n > self.b.length() {
    raise TursoError::QueryError("truncated result buffer")
  }
  let out = self.b[self.p:self.p + n].to_owned()
  self.p = self.p + n
  out
}

///|
/// 读一帧:`u8 tag + u32 len + payload`。返回 (tag, payload)。
async fn read_frame(s : @raw_fd.RawFdStream) -> (Int, Bytes) raise TursoError {
  let head = s.read_exactly(5) catch {
    _ => raise TursoError::ConnectionError("failed to read result frame")
  }
  let tag = head[0].to_int()
  let len = head[1].to_int() |
    (head[2].to_int() << 8) |
    (head[3].to_int() << 16) |
    (head[4].to_int() << 24)
  let payload = s.read_exactly(len) catch {
    _ => raise TursoError::ConnectionError("failed to read result payload")
  }
  (tag, payload)
}

///|
/// ERR 帧的 payload = `u8 kind + 消息`。
fn stream_error(payload : Bytes) -> TursoError {
  if payload.length() == 0 {
    return TursoError::QueryError("stream error")
  }
  kind_to_error(payload[0].to_int(), @utf8.decode_lossy(payload[1:].to_owned()))
}

///|
fn parse_columns(payload : Bytes) -> Array[@value.Column] raise TursoError {
  let rd : Rd = { b: payload, p: 0, }
  let n = rd.u32()
  let cols : Array[@value.Column] = []
  for _ in 0.. (Array[@value.Value], Array[Bytes]) raise TursoError {
  let rd : Rd = { b: payload, p: 0, }
  let vals : Array[@value.Value] = []
  let raws : Array[Bytes] = []
  for _ in 0..