use serde::de::Error as _;
use serde::{Deserialize, Deserializer, Serialize};
use serde_json::Value;
use std::collections::HashSet;
use crate::error::{ErrorCode, Result, TabularkError};
use crate::model::{MAX_SAFE_INTEGER, RangeRequest, TableMetadata, TypedTableBatch};
pub const LEGACY_PROTOCOL_VERSION: u32 = 1;
pub const PROTOCOL_V2_VERSION: u32 = 2;
pub const PREVIOUS_PROTOCOL_VERSION: u32 = 3;
pub const PROTOCOL_VERSION: u32 = 4;
pub const ADAPTER_API_VERSION: u32 = 3;
pub const MAX_OPERATION_RANGES_PER_STEP: usize = 32;
pub use crate::model::BATCH_LAYOUT_VERSION;
pub const DELIMITED_ADAPTER_ID: &str = "tabulark:delimited";
pub const ARROW_IPC_ADAPTER_ID: &str = "tabulark:arrow-ipc";
pub const PARQUET_ADAPTER_ID: &str = "tabulark:parquet";
pub const EXCEL_ADAPTER_ID: &str = "tabulark:excel";
#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)]
#[serde(
tag = "kind",
rename_all = "kebab-case",
rename_all_fields = "camelCase"
)]
pub enum AdapterAction {
ReadBytes {
action_index: u32,
offset: u64,
length: u64,
},
}
impl AdapterAction {
#[must_use]
pub const fn read_bytes(offset: u64, length: u64) -> Self {
Self::ReadBytes {
action_index: 0,
offset,
length,
}
}
#[must_use]
pub const fn indexed_read_bytes(action_index: u32, offset: u64, length: u64) -> Self {
Self::ReadBytes {
action_index,
offset,
length,
}
}
#[must_use]
pub const fn action_index(self) -> u32 {
match self {
Self::ReadBytes { action_index, .. } => action_index,
}
}
#[must_use]
pub const fn offset(self) -> u64 {
match self {
Self::ReadBytes { offset, .. } => offset,
}
}
#[must_use]
pub const fn length(self) -> u64 {
match self {
Self::ReadBytes { length, .. } => length,
}
}
pub fn end(self) -> Result<u64> {
self.offset().checked_add(self.length()).ok_or_else(|| {
TabularkError::new(
ErrorCode::InvalidArgument,
"adapter source action range overflows u64",
)
.with_detail("actionIndex", self.action_index())
.with_detail("offset", self.offset())
.with_detail("length", self.length())
})
}
}
#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct AdapterActionResult {
pub action_index: u32,
pub offset: u64,
pub length: u64,
pub eof: bool,
}
#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)]
#[serde(rename_all = "kebab-case")]
pub enum AdapterStepKind {
Pending,
Progress,
Complete,
}
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct AdapterStep {
pub kind: AdapterStepKind,
pub operation_handle: u32,
pub operation_revision: u64,
pub actions: Vec<AdapterAction>,
pub cooperative_yield: bool,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub payload: Option<Value>,
}
impl AdapterStep {
pub fn new(
kind: AdapterStepKind,
operation_handle: u32,
operation_revision: u64,
actions: Vec<AdapterAction>,
cooperative_yield: bool,
payload: Option<Value>,
operation_budget_bytes: u64,
) -> Result<Self> {
validate_operation_actions(&actions, operation_budget_bytes)?;
if operation_revision == 0 || operation_revision > MAX_SAFE_INTEGER {
return Err(TabularkError::new(
ErrorCode::InvalidArgument,
"operation revision must be a positive JavaScript safe integer",
)
.with_detail("operationRevision", operation_revision.to_string()));
}
if kind == AdapterStepKind::Complete && (!actions.is_empty() || cooperative_yield) {
return Err(TabularkError::new(
ErrorCode::InvalidArgument,
"a complete operation step cannot request more work",
));
}
if kind != AdapterStepKind::Complete && actions.is_empty() && !cooperative_yield {
return Err(TabularkError::new(
ErrorCode::InvalidArgument,
"a non-terminal operation step must request I/O or an explicit cooperative yield",
));
}
if !actions.is_empty() && cooperative_yield {
return Err(TabularkError::new(
ErrorCode::InvalidArgument,
"an operation step cannot request I/O and a cooperative yield together",
));
}
Ok(Self {
kind,
operation_handle,
operation_revision,
actions,
cooperative_yield,
payload,
})
}
}
#[derive(Clone, Debug, Default)]
pub struct AdapterOperationCursor {
revision: u64,
outstanding: Vec<AdapterAction>,
awaiting_results: bool,
}
impl AdapterOperationCursor {
#[must_use]
pub const fn new() -> Self {
Self {
revision: 0,
outstanding: Vec::new(),
awaiting_results: false,
}
}
pub fn issue(
&mut self,
actions: Vec<AdapterAction>,
operation_budget_bytes: u64,
) -> Result<u64> {
if self.awaiting_results {
return Err(TabularkError::new(
ErrorCode::RuntimeFailure,
"operation already has outstanding source actions",
));
}
validate_operation_actions(&actions, operation_budget_bytes)?;
let revision = self.revision.checked_add(1).ok_or_else(|| {
TabularkError::new(
ErrorCode::ResourceLimit,
"operation revision space is exhausted",
)
})?;
if revision > MAX_SAFE_INTEGER {
return Err(TabularkError::new(
ErrorCode::ResourceLimit,
"operation revision exceeds the JavaScript safe integer range",
));
}
self.revision = revision;
self.outstanding = actions;
self.awaiting_results = true;
Ok(revision)
}
pub fn complete_revision(&mut self) -> Result<u64> {
if self.awaiting_results {
return Err(TabularkError::new(
ErrorCode::RuntimeFailure,
"operation cannot complete with outstanding source actions",
));
}
let revision = self.revision.checked_add(1).ok_or_else(|| {
TabularkError::new(
ErrorCode::ResourceLimit,
"operation revision space is exhausted",
)
})?;
if revision > MAX_SAFE_INTEGER {
return Err(TabularkError::new(
ErrorCode::ResourceLimit,
"operation revision exceeds the JavaScript safe integer range",
));
}
self.revision = revision;
Ok(revision)
}
pub fn validate_results(
&mut self,
operation_revision: u64,
results: &[AdapterActionResult],
) -> Result<()> {
if operation_revision != self.revision {
return Err(TabularkError::new(
ErrorCode::InvalidArgument,
"operation result revision is missing, stale, or out of order",
)
.with_detail("expectedOperationRevision", self.revision)
.with_detail("actualOperationRevision", operation_revision));
}
if !self.awaiting_results {
return Err(TabularkError::new(
ErrorCode::InvalidArgument,
"operation revision has already consumed its result set",
)
.with_detail("operationRevision", operation_revision));
}
if results.len() != self.outstanding.len() {
return Err(TabularkError::new(
ErrorCode::InvalidArgument,
"operation result set is missing or contains extra source ranges",
)
.with_detail("expectedResults", self.outstanding.len())
.with_detail("actualResults", results.len()));
}
let mut seen = HashSet::with_capacity(results.len());
for result in results {
if !seen.insert(result.action_index) {
return Err(TabularkError::new(
ErrorCode::InvalidArgument,
"operation result set contains a duplicate source range",
)
.with_detail("actionIndex", result.action_index));
}
let expected = self
.outstanding
.iter()
.copied()
.find(|action| action.action_index() == result.action_index)
.ok_or_else(|| {
TabularkError::new(
ErrorCode::InvalidArgument,
"operation result references an unknown source range",
)
.with_detail("actionIndex", result.action_index)
})?;
let actual_end = result.offset.checked_add(result.length).ok_or_else(|| {
TabularkError::new(
ErrorCode::InvalidArgument,
"operation result source range overflows u64",
)
.with_detail("actionIndex", result.action_index)
})?;
if expected.offset() != result.offset
|| expected.length() != result.length
|| expected.end()? != actual_end
{
return Err(TabularkError::new(
ErrorCode::InvalidArgument,
"operation result does not match its requested source range",
)
.with_detail("actionIndex", result.action_index)
.with_detail("expectedOffset", expected.offset())
.with_detail("expectedLength", expected.length())
.with_detail("actualOffset", result.offset)
.with_detail("actualLength", result.length));
}
}
self.outstanding.clear();
self.awaiting_results = false;
Ok(())
}
#[must_use]
pub const fn revision(&self) -> u64 {
self.revision
}
}
pub fn validate_operation_actions(
actions: &[AdapterAction],
operation_budget_bytes: u64,
) -> Result<u64> {
if actions.len() > MAX_OPERATION_RANGES_PER_STEP {
return Err(TabularkError::new(
ErrorCode::ResourceLimit,
"operation step requests too many source ranges",
)
.with_detail("rangeCount", actions.len())
.with_detail("maxRangeCount", MAX_OPERATION_RANGES_PER_STEP));
}
let mut ids = HashSet::with_capacity(actions.len());
let mut total = 0_u64;
for action in actions {
if !ids.insert(action.action_index()) {
return Err(TabularkError::new(
ErrorCode::InvalidArgument,
"operation step contains a duplicate source action ID",
)
.with_detail("actionIndex", action.action_index()));
}
if action.offset() > MAX_SAFE_INTEGER
|| action.length() > MAX_SAFE_INTEGER
|| action.end()? > MAX_SAFE_INTEGER
{
return Err(TabularkError::new(
ErrorCode::ResourceLimit,
"operation source range exceeds the JavaScript safe integer boundary",
)
.with_detail("actionIndex", action.action_index()));
}
total = total.checked_add(action.length()).ok_or_else(|| {
TabularkError::new(
ErrorCode::ResourceLimit,
"operation step source byte total overflows u64",
)
})?;
}
if total > operation_budget_bytes {
return Err(TabularkError::new(
ErrorCode::ResourceLimit,
"operation step exceeds its source byte budget",
)
.with_detail("requestedBytes", total)
.with_detail("operationBudgetBytes", operation_budget_bytes));
}
Ok(total)
}
pub fn checked_wasm32_usize(value: u64, field: &str) -> Result<usize> {
let narrowed = u32::try_from(value).map_err(|_| {
TabularkError::new(
ErrorCode::ResourceLimit,
"value exceeds the wasm32 usize range",
)
.with_detail("field", field)
.with_detail("value", value.to_string())
})?;
usize::try_from(narrowed).map_err(|_| {
TabularkError::new(
ErrorCode::ResourceLimit,
"wasm32 usize value is unavailable on this validation target",
)
.with_detail("field", field)
})
}
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct AdapterTableDescriptor {
pub id: String,
pub name: String,
}
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct AdapterProgress {
pub source_handle: u32,
pub bytes_scanned: u64,
pub rows_discovered: u64,
pub done: bool,
}
pub fn ensure_protocol_version(actual: u32) -> Result<()> {
if actual != PROTOCOL_VERSION {
return Err(TabularkError::new(
ErrorCode::ProtocolIncompatible,
"the peer uses an unsupported Worker protocol version",
)
.with_detail("expectedProtocolVersion", PROTOCOL_VERSION)
.with_detail("actualProtocolVersion", actual));
}
Ok(())
}
fn deserialize_protocol_version<'de, D>(deserializer: D) -> std::result::Result<u32, D::Error>
where
D: Deserializer<'de>,
{
let version = u32::deserialize(deserializer)?;
ensure_protocol_version(version).map_err(D::Error::custom)?;
Ok(version)
}
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct RequestEnvelope {
#[serde(deserialize_with = "deserialize_protocol_version")]
protocol_version: u32,
request_id: String,
#[serde(flatten)]
request: Request,
}
impl RequestEnvelope {
#[must_use]
pub fn new(request_id: impl Into<String>, request: Request) -> Self {
Self {
protocol_version: PROTOCOL_VERSION,
request_id: request_id.into(),
request,
}
}
#[must_use]
pub const fn protocol_version(&self) -> u32 {
self.protocol_version
}
#[must_use]
pub fn request_id(&self) -> &str {
&self.request_id
}
#[must_use]
pub const fn request(&self) -> &Request {
&self.request
}
}
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(tag = "op", content = "payload", rename_all = "camelCase")]
#[non_exhaustive]
pub enum Request {
Hello(HelloRequest),
OpenSource(OpenSourceRequest),
ListTables(DatasetRequest),
OpenTable(OpenTableRequest),
GetMetadata(TableRequest),
GetPresentation(TableRequest),
ReadPresentationRange(ReadPresentationRangeRequest),
ReadRange(ReadRangeRequest),
Cancel(CancelRequest),
CloseTable(TableRequest),
CloseSource(DatasetRequest),
Shutdown,
}
#[derive(Clone, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct HelloRequest {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub client_name: Option<String>,
#[serde(default)]
pub adapters: Vec<AdapterRegistration>,
#[serde(default)]
pub memory_budget_bytes: u64,
}
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct AdapterRegistration {
pub id: String,
pub module_url: String,
}
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct OpenSourceRequest {
pub adapter_id: String,
#[serde(default)]
pub options: Value,
}
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct DatasetRequest {
pub dataset_handle: String,
}
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct TableRequest {
pub table_handle: String,
}
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct OpenTableRequest {
pub dataset_handle: String,
pub table_id: String,
}
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct ReadRangeRequest {
pub table_handle: String,
pub range: RangeRequest,
}
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct ReadPresentationRangeRequest {
pub table_handle: String,
pub range: RangeRequest,
}
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct CancelRequest {
pub target_request_id: String,
}
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct ResponseEnvelope {
#[serde(deserialize_with = "deserialize_protocol_version")]
protocol_version: u32,
request_id: String,
#[serde(flatten)]
response: Response,
}
impl ResponseEnvelope {
#[must_use]
pub fn success(request_id: impl Into<String>, result: ResponseResult) -> Self {
Self {
protocol_version: PROTOCOL_VERSION,
request_id: request_id.into(),
response: Response::Success { result },
}
}
#[must_use]
pub fn failure(request_id: impl Into<String>, error: TabularkError) -> Self {
Self {
protocol_version: PROTOCOL_VERSION,
request_id: request_id.into(),
response: Response::Failure { error },
}
}
#[must_use]
pub fn request_id(&self) -> &str {
&self.request_id
}
#[must_use]
pub const fn protocol_version(&self) -> u32 {
self.protocol_version
}
#[must_use]
pub const fn response(&self) -> &Response {
&self.response
}
}
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(tag = "status", rename_all = "camelCase")]
pub enum Response {
Success {
result: ResponseResult,
},
Failure {
error: TabularkError,
},
}
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(tag = "kind", content = "data", rename_all = "camelCase")]
#[non_exhaustive]
pub enum ResponseResult {
Hello(HelloResponse),
Dataset(DatasetDescriptor),
Tables(Vec<TableDescriptor>),
Table(TableDescriptor),
Metadata(TableMetadata),
Presentation(Option<Value>),
PresentationRange(Option<Value>),
Batch(TypedTableBatch),
Acknowledged,
}
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct HelloResponse {
#[serde(deserialize_with = "deserialize_protocol_version")]
pub protocol_version: u32,
pub adapter_api_version: u32,
pub batch_layout_version: u32,
pub adapters: Vec<String>,
pub transferable_batches: bool,
}
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct DatasetDescriptor {
pub dataset_handle: String,
}
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct TableDescriptor {
pub id: String,
pub name: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub table_handle: Option<String>,
}
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct EventEnvelope {
#[serde(deserialize_with = "deserialize_protocol_version")]
pub protocol_version: u32,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub request_id: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub dataset_handle: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub table_handle: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub table_id: Option<String>,
#[serde(flatten)]
pub event: RuntimeEvent,
}
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(tag = "event", content = "payload", rename_all = "camelCase")]
#[non_exhaustive]
pub enum RuntimeEvent {
Progress(ProgressEvent),
Metadata(TableMetadata),
Warning(WarningEvent),
Closed(ClosedEvent),
RuntimeError(TabularkError),
}
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct ProgressEvent {
pub source_handle: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub table_id: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub revision: Option<u64>,
pub bytes_scanned: u64,
pub rows_discovered: u64,
pub done: bool,
}
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct WarningEvent {
pub handle: String,
pub kind: String,
pub message: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub byte_offset: Option<u64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub row: Option<u64>,
}
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct ClosedEvent {
pub handle: String,
pub kind: String,
}
#[cfg(test)]
mod tests {
use std::fs;
use std::path::Path;
use super::{
ADAPTER_API_VERSION, ARROW_IPC_ADAPTER_ID, AdapterAction, AdapterActionResult,
AdapterOperationCursor, AdapterStep, AdapterStepKind, BATCH_LAYOUT_VERSION,
DELIMITED_ADAPTER_ID, EXCEL_ADAPTER_ID, EventEnvelope, HelloRequest,
LEGACY_PROTOCOL_VERSION, MAX_OPERATION_RANGES_PER_STEP, PARQUET_ADAPTER_ID,
PREVIOUS_PROTOCOL_VERSION, PROTOCOL_V2_VERSION, PROTOCOL_VERSION,
ReadPresentationRangeRequest, Request, RequestEnvelope, ResponseEnvelope, ResponseResult,
checked_wasm32_usize, ensure_protocol_version, validate_operation_actions,
};
use crate::error::ErrorCode;
use crate::model::RangeRequest;
#[test]
fn request_wire_shape_is_flat_and_versioned() {
let request = RequestEnvelope::new(
"request-1",
Request::Hello(HelloRequest {
client_name: Some("test".into()),
adapters: vec![],
memory_budget_bytes: 268_435_456,
}),
);
assert_eq!(
serde_json::to_value(request).expect("serialize request"),
serde_json::json!({
"protocolVersion": PROTOCOL_VERSION,
"requestId": "request-1",
"op": "hello",
"payload": {
"clientName": "test",
"adapters": [],
"memoryBudgetBytes": 268435456
}
})
);
}
#[test]
fn shared_v1_golden_fixtures_remain_historical_evidence() {
let root = Path::new(env!("CARGO_MANIFEST_DIR")).join("test/fixtures/protocol/v1");
if !root.exists() {
return;
}
for name in [
"hello-request.json",
"open-source-request.json",
"read-range-request.json",
"hello-response.json",
"close-response.json",
"invalid-range-response.json",
"metadata-event.json",
"warning-event.json",
] {
let source = fs::read_to_string(root.join(name)).expect("read protocol fixture");
let fixture: serde_json::Value =
serde_json::from_str(&source).expect("parse fixture JSON");
assert_eq!(
fixture["protocolVersion"], LEGACY_PROTOCOL_VERSION,
"fixture {name} is no longer protocol v1 evidence"
);
}
}
#[test]
fn historical_protocols_are_rejected_at_every_rust_envelope_boundary() {
for historical in [
LEGACY_PROTOCOL_VERSION,
PROTOCOL_V2_VERSION,
PREVIOUS_PROTOCOL_VERSION,
] {
let error = ensure_protocol_version(historical)
.expect_err("historical protocol must be rejected");
assert_eq!(error.code(), ErrorCode::ProtocolIncompatible);
assert_eq!(error.details()["expectedProtocolVersion"], PROTOCOL_VERSION);
assert_eq!(error.details()["actualProtocolVersion"], historical);
}
let root = Path::new(env!("CARGO_MANIFEST_DIR")).join("test/fixtures/protocol/v1");
if !root.exists() {
return;
}
let request = fs::read_to_string(root.join("hello-request.json")).expect("request");
assert!(serde_json::from_str::<RequestEnvelope>(&request).is_err());
let response = fs::read_to_string(root.join("hello-response.json")).expect("response");
assert!(serde_json::from_str::<ResponseEnvelope>(&response).is_err());
let event = fs::read_to_string(root.join("warning-event.json")).expect("event");
assert!(serde_json::from_str::<EventEnvelope>(&event).is_err());
}
#[test]
fn shared_v2_golden_fixtures_remain_historical_evidence() {
let root = Path::new(env!("CARGO_MANIFEST_DIR")).join("test/fixtures/protocol/v2");
if !root.exists() {
return;
}
for name in [
"hello-request.json",
"open-arrow-request.json",
"hello-response.json",
"metadata-event.json",
] {
let source = fs::read_to_string(root.join(name)).expect("read protocol fixture");
let fixture: serde_json::Value =
serde_json::from_str(&source).expect("parse fixture JSON");
assert_eq!(fixture["protocolVersion"], PROTOCOL_V2_VERSION);
}
}
#[test]
fn shared_v3_golden_fixtures_remain_historical_evidence() {
let root = Path::new(env!("CARGO_MANIFEST_DIR")).join("test/fixtures/protocol/v3");
if !root.exists() {
return;
}
for entry in fs::read_dir(root).expect("read v3 fixture directory") {
let path = entry.expect("v3 fixture entry").path();
if path
.extension()
.is_some_and(|extension| extension == "json")
{
let source = fs::read_to_string(&path).expect("read v3 fixture");
let fixture: serde_json::Value =
serde_json::from_str(&source).expect("parse v3 fixture");
assert_eq!(fixture["protocolVersion"], PREVIOUS_PROTOCOL_VERSION);
}
}
}
#[test]
fn adapter_and_layout_versions_are_independent_of_protocol_v4() {
assert_eq!(PROTOCOL_VERSION, 4);
assert_eq!(ADAPTER_API_VERSION, 3);
assert_eq!(BATCH_LAYOUT_VERSION, 1);
assert_eq!(DELIMITED_ADAPTER_ID, "tabulark:delimited");
assert_eq!(ARROW_IPC_ADAPTER_ID, "tabulark:arrow-ipc");
assert_eq!(PARQUET_ADAPTER_ID, "tabulark:parquet");
assert_eq!(EXCEL_ADAPTER_ID, "tabulark:excel");
}
#[test]
fn adapter_v3_steps_have_one_state_revision_and_action_array() {
let step = AdapterStep::new(
AdapterStepKind::Pending,
7,
1,
vec![AdapterAction::indexed_read_bytes(0, 1024, 4096)],
false,
None,
4096,
)
.expect("valid adapter step");
assert_eq!(
serde_json::to_value(step).expect("serialize adapter step"),
serde_json::json!({
"kind": "pending",
"operationHandle": 7,
"operationRevision": 1,
"actions": [{
"kind": "read-bytes",
"actionIndex": 0,
"offset": 1024,
"length": 4096
}],
"cooperativeYield": false
})
);
}
#[test]
fn operation_cursor_rejects_missing_duplicate_stale_and_out_of_bounds_results() {
let mut cursor = AdapterOperationCursor::new();
let actions = vec![
AdapterAction::indexed_read_bytes(0, 0, 4),
AdapterAction::indexed_read_bytes(1, 16, 2),
];
let revision = cursor.issue(actions, 6).expect("issue ranges");
assert_eq!(revision, 1);
let first = AdapterActionResult {
action_index: 0,
offset: 0,
length: 4,
eof: false,
};
let second = AdapterActionResult {
action_index: 1,
offset: 16,
length: 2,
eof: true,
};
for malformed in [vec![first], vec![first, first]] {
assert_eq!(
cursor
.validate_results(revision, &malformed)
.expect_err("malformed result set")
.code(),
ErrorCode::InvalidArgument
);
}
let out_of_bounds = AdapterActionResult {
length: 3,
..second
};
assert_eq!(
cursor
.validate_results(revision, &[first, out_of_bounds])
.expect_err("out-of-bounds result")
.code(),
ErrorCode::InvalidArgument
);
assert_eq!(
cursor
.validate_results(revision + 1, &[first, second])
.expect_err("future result")
.code(),
ErrorCode::InvalidArgument
);
cursor
.validate_results(revision, &[first, second])
.expect("exact result set");
let next = cursor
.issue(vec![AdapterAction::indexed_read_bytes(0, 18, 1)], 1)
.expect("next revision");
assert_eq!(next, 2);
assert_eq!(
cursor
.validate_results(revision, &[])
.expect_err("stale result")
.code(),
ErrorCode::InvalidArgument
);
}
#[test]
fn operation_action_limits_are_checked_without_allocating_large_sources() {
let too_many = (0..=MAX_OPERATION_RANGES_PER_STEP)
.map(|index| AdapterAction::indexed_read_bytes(index as u32, index as u64, 1))
.collect::<Vec<_>>();
assert_eq!(
validate_operation_actions(&too_many, u64::MAX)
.expect_err("range count")
.code(),
ErrorCode::ResourceLimit
);
assert_eq!(
validate_operation_actions(
&[AdapterAction::indexed_read_bytes(0, u64::MAX, 2)],
u64::MAX,
)
.expect_err("offset overflow")
.code(),
ErrorCode::ResourceLimit
);
assert_eq!(
validate_operation_actions(&[AdapterAction::indexed_read_bytes(0, 0, 7)], 6,)
.expect_err("operation budget")
.code(),
ErrorCode::ResourceLimit
);
let above_exact_product_limit = (1_u64 << 31) + 1;
assert_eq!(
validate_operation_actions(
&[AdapterAction::indexed_read_bytes(
0,
above_exact_product_limit,
1,
)],
1,
)
.expect("u64 ABI preserves offsets above the product limit"),
1
);
assert!(checked_wasm32_usize(1_u64 << 31, "sourceLength").is_ok());
assert!(checked_wasm32_usize(above_exact_product_limit, "offset").is_ok());
assert_eq!(
checked_wasm32_usize(1_u64 << 32, "offset")
.expect_err("wasm32 usize overflow")
.code(),
ErrorCode::ResourceLimit
);
assert!(
validate_operation_actions(
&[AdapterAction::indexed_read_bytes(
0,
crate::model::MAX_SAFE_INTEGER,
0,
)],
0,
)
.is_ok()
);
assert_eq!(
validate_operation_actions(
&[AdapterAction::indexed_read_bytes(
0,
crate::model::MAX_SAFE_INTEGER,
1,
)],
1,
)
.expect_err("safe-integer end overflow")
.code(),
ErrorCode::ResourceLimit
);
}
#[test]
fn adapter_v3_supports_an_explicit_no_io_yield() {
let step = AdapterStep::new(AdapterStepKind::Pending, 9, 1, vec![], true, None, 0)
.expect("cooperative yield");
assert!(step.actions.is_empty());
assert!(step.cooperative_yield);
}
#[test]
fn protocol_v4_carries_nullable_presentation_queries() {
let range = RangeRequest::new(4, 2, 3, 1).expect("range");
let request = RequestEnvelope::new(
"presentation-1",
Request::ReadPresentationRange(ReadPresentationRangeRequest {
table_handle: "table-handle".into(),
range,
}),
);
assert_eq!(
serde_json::to_value(request).expect("serialize request"),
serde_json::json!({
"protocolVersion": 4,
"requestId": "presentation-1",
"op": "readPresentationRange",
"payload": {
"tableHandle": "table-handle",
"range": {
"rowStart": 4,
"rowCount": 2,
"columnStart": 3,
"columnCount": 1
}
}
})
);
let response =
ResponseEnvelope::success("presentation-1", ResponseResult::PresentationRange(None));
assert_eq!(
serde_json::to_value(response).expect("serialize response"),
serde_json::json!({
"protocolVersion": 4,
"requestId": "presentation-1",
"status": "success",
"result": {
"kind": "presentationRange",
"data": null
}
})
);
}
}