blob: 8e471d78c7793ccab98ed098bb1e1b8cce69fa9c [file]
// Licensed to the Apache Software Foundation (ASF) under one or more
// contributor license agreements. See the NOTICE file distributed with
// this work for additional information regarding copyright ownership.
// The ASF licenses this file to You under the Apache License, Version 2.0
// (the "License"); you may not use this file except in compliance with
// the License. You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//! Driver-only handles of sources, scans, streams, and writes, and executor readers restored
//! from serialized values.
use std::any::Any;
use std::collections::HashMap;
use std::ffi::CString;
use std::panic::{catch_unwind, AssertUnwindSafe};
use std::sync::atomic::{AtomicI64, Ordering};
use std::sync::{Arc, Mutex, MutexGuard};
use arrow_array::ffi_stream::FFI_ArrowArrayStream;
use arrow_schema::SchemaRef;
use serde::{de::DeserializeOwned, Deserialize, Serialize};
use crate::write::{Batch, DriverWrite, DriverWriter};
use crate::{
abi, BatchWrite, Capabilities, CommitOffsetInfo, CreateInfo, DataSource, LatestOffsetInfo,
LimitSupport, MicroBatchInfo, MicroBatchStream, MicroBatchStreamInfo, PartitionReaderFactory,
ReadLimit, ReaderContext, Result, ScanBuilder, ScanInfo, ScanPlan, StreamingWrite,
StreamingWriteInfo, TaskContext, WriteInfo, WriteMode,
};
#[path = "stream.rs"]
pub(crate) mod stream;
const STATE_VERSION: u32 = 1;
type HandleMap<T> = Mutex<HashMap<i64, Arc<Mutex<T>>>>;
/// One registry per loaded plugin. Provider code runs under a per-handle lock,
/// so independent sources, scans, and streams do not serialize behind a global lock.
pub struct Bridge<S: DataSource> {
next_handle: AtomicI64,
sources: HandleMap<SourceState<S>>,
// The builder of each scan, until Spark plans the scan.
scans: HandleMap<Option<S::ScanBuilder>>,
streams: HandleMap<S::MicroBatchStream>,
writers: HandleMap<Box<dyn DriverWrite>>,
}
impl<S: DataSource> Default for Bridge<S> {
fn default() -> Self {
Self {
next_handle: AtomicI64::new(1),
sources: Mutex::new(HashMap::new()),
scans: Mutex::new(HashMap::new()),
streams: Mutex::new(HashMap::new()),
writers: Mutex::new(HashMap::new()),
}
}
}
/// The partitions of a scan or a micro-batch, and the state of its reader: its factory.
pub struct EncodedPlan {
pub state: Vec<u8>,
pub partitions: Vec<Vec<u8>>,
}
impl<S: DataSource> Bridge<S> {
// Whether the source implements each operation, whose native callbacks the SDK installs.
pub const READ: bool = <S::ScanBuilder as ScanBuilder>::SUPPORTED;
pub const MICRO_BATCH_READ: bool = <S::MicroBatchStream as MicroBatchStream>::SUPPORTED;
pub const WRITE: bool = <S::BatchWrite as BatchWrite>::SUPPORTED;
pub const STREAMING_WRITE: bool = <S::StreamingWrite as StreamingWrite>::SUPPORTED;
const CAPABILITIES: Capabilities = Capabilities::implemented(&[
(Capabilities::BATCH_READ, Self::READ),
(Capabilities::MICRO_BATCH_READ, Self::MICRO_BATCH_READ),
(Capabilities::BATCH_WRITE, Self::WRITE),
(Capabilities::STREAMING_WRITE, Self::STREAMING_WRITE),
(
Capabilities::BATCH_TRUNCATE,
<S::BatchWrite as BatchWrite>::SUPPORTS_TRUNCATE,
),
(
Capabilities::STREAMING_TRUNCATE,
<S::StreamingWrite as StreamingWrite>::SUPPORTS_TRUNCATE,
),
]);
fn insert<T>(&self, handles: &HandleMap<T>, value: T) -> Result<i64> {
let handle = self
.next_handle
.fetch_update(Ordering::Relaxed, Ordering::Relaxed, |id| id.checked_add(1))
.map_err(|_| "native handle IDs exhausted")?;
lock(handles).insert(handle, Arc::new(Mutex::new(value)));
Ok(handle)
}
pub fn create(&self, info: CreateInfo) -> Result<(i64, u64)> {
self.register_source(S::new(info)?)
}
fn register_source(&self, source: S) -> Result<(i64, u64)> {
let capabilities = Self::effective(source.capabilities());
let handle = self.insert(
&self.sources,
SourceState {
source,
capabilities,
},
)?;
// Every stream supports admission control: its default read limit is all the
// available data unless it overrides MicroBatchStream::default_read_limit.
let admission_control = if capabilities.contains(Capabilities::MICRO_BATCH_READ) {
abi::ADMISSION_CONTROL
} else {
0
};
Ok((handle, capabilities.bits() | admission_control))
}
/// Keeps the implemented operations of a declaration, so that a source can narrow its
/// operations but never add one, and each truncation only with its write.
fn effective(declared: Capabilities) -> Capabilities {
let mut capabilities = declared.intersection(Self::CAPABILITIES);
for (write, truncate) in [
(Capabilities::BATCH_WRITE, Capabilities::BATCH_TRUNCATE),
(
Capabilities::STREAMING_WRITE,
Capabilities::STREAMING_TRUNCATE,
),
] {
if !capabilities.contains(write) {
capabilities = capabilities.without(truncate);
}
}
capabilities
}
pub fn schema(&self, handle: i64) -> Result<SchemaRef> {
let source = get(&self.sources, handle)?;
let schema = lock(&source).source.infer_schema()?;
stream::validate_schema(&schema)?;
Ok(schema)
}
pub fn create_reader(&self, handle: i64, schema: SchemaRef) -> Result<i64> {
stream::validate_schema(&schema)?;
let source = get(&self.sources, handle)?;
let builder = {
let source = lock(&source);
require(source.capabilities, Capabilities::BATCH_READ, "batch reads")?;
source.source.new_scan(ScanInfo::new(schema))?
};
self.insert(&self.scans, Some(builder))
}
pub fn push_limit(&self, handle: i64, limit: usize) -> Result<bool> {
let scan = get(&self.scans, handle)?;
let mut scan = lock(&scan);
Ok(builder(&mut scan)?.push_limit(limit)? == LimitSupport::Global)
}
pub fn prune_columns(&self, handle: i64, columns: &[String]) -> Result<()> {
let scan = get(&self.scans, handle)?;
let mut scan = lock(&scan);
builder(&mut scan)?.prune_columns(columns)
}
/// Plans a scan, which consumes its builder.
pub fn plan(&self, handle: i64) -> Result<EncodedPlan> {
let scan = get(&self.scans, handle)?;
let builder = lock(&scan)
.take()
.ok_or("the scan has already been planned")?;
encode_plan(builder.plan()?)
}
pub fn close_reader(&self, handle: i64) -> Result<()> {
remove(&self.scans, handle);
Ok(())
}
pub fn create_stream_reader(&self, handle: i64, info: MicroBatchStreamInfo) -> Result<i64> {
stream::validate_schema(&info.schema)?;
let source = get(&self.sources, handle)?;
let stream = {
let source = lock(&source);
require(
source.capabilities,
Capabilities::MICRO_BATCH_READ,
"micro-batch streaming reads",
)?;
source.source.new_micro_batch_stream(info)?
};
self.insert(&self.streams, stream)
}
pub fn initial_offset(&self, handle: i64) -> Result<String> {
let stream = get(&self.streams, handle)?;
let offset = lock(&stream).initial_offset()?;
encode_offset(&offset)
}
pub fn default_read_limit(&self, handle: i64) -> Result<ReadLimit> {
let stream = get(&self.streams, handle)?;
let limit = lock(&stream).default_read_limit();
limit
}
/// Decodes the offsets of a request, and encodes the latest offset.
pub fn latest_offset(&self, handle: i64, info: LatestOffsetInfo<String>) -> Result<String> {
let stream = get(&self.streams, handle)?;
let info = LatestOffsetInfo {
start: decode_offset(&info.start)?,
limit: info.limit,
run_end: info.run_end.as_deref().map(decode_offset).transpose()?,
};
let offset = lock(&stream).latest_offset(info)?;
encode_offset(&offset)
}
pub fn stream_partitions(&self, handle: i64, start: &str, end: &str) -> Result<EncodedPlan> {
let stream = get(&self.streams, handle)?;
let info = MicroBatchInfo::new(decode_offset(start)?, decode_offset(end)?);
let plan = lock(&stream).plan(info)?;
encode_plan(plan)
}
pub fn commit_offset(&self, handle: i64, end: &str) -> Result<()> {
let stream = get(&self.streams, handle)?;
let info = CommitOffsetInfo::new(decode_offset(end)?);
let result = lock(&stream).commit(info);
result
}
pub fn close_stream_reader(&self, handle: i64) -> Result<()> {
remove(&self.streams, handle);
Ok(())
}
/// Creates a batch write, or the write of a micro-batch of the streaming query `query_id`,
/// with the state of its task writers.
pub fn create_writer(
&self,
handle: i64,
schema: SchemaRef,
mode: WriteMode,
query_id: Option<String>,
) -> Result<(i64, Vec<u8>)> {
stream::validate_schema(&schema)?;
let source = get(&self.sources, handle)?;
let (writer, state) = {
let source = lock(&source);
let capabilities = source.capabilities;
let truncate = mode == WriteMode::Truncate;
match query_id {
None => {
require(capabilities, Capabilities::BATCH_WRITE, "batch writes")?;
if truncate {
let overwrite = "the save mode overwrite";
require(capabilities, Capabilities::BATCH_TRUNCATE, overwrite)?;
}
let write = source.source.new_write(WriteInfo::new(schema, mode))?;
DriverWriter::create(Batch(write))?
}
Some(query_id) => {
require(
capabilities,
Capabilities::STREAMING_WRITE,
"streaming writes",
)?;
if truncate {
let complete = "the output mode complete";
require(capabilities, Capabilities::STREAMING_TRUNCATE, complete)?;
}
let info = StreamingWriteInfo::new(schema, mode, query_id);
let write = source.source.new_streaming_write(info)?;
DriverWriter::create(write)?
}
}
};
Ok((self.insert(&self.writers, writer)?, state))
}
pub fn commit(&self, handle: i64, epoch_id: i64, messages: &[Option<&[u8]>]) -> Result<()> {
let writer = get(&self.writers, handle)?;
let result = lock(&writer).commit(epoch_id, messages);
result
}
pub fn abort(&self, handle: i64, epoch_id: i64, messages: &[Option<&[u8]>]) -> Result<()> {
let writer = get(&self.writers, handle)?;
let result = lock(&writer).abort(epoch_id, messages);
result
}
pub fn close_writer(&self, handle: i64) -> Result<()> {
remove(&self.writers, handle);
Ok(())
}
pub fn close_source(&self, handle: i64) -> Result<()> {
remove(&self.sources, handle);
Ok(())
}
}
/// Opens the executor reader of a partition with factory `F`, using only serialized values.
/// No source, scan, stream, or driver handle registry is created or consulted.
///
/// # Safety
/// `task` must satisfy TaskContext::from_raw and remain valid until the
/// returned stream is released. The stream's consumer must follow the
/// Arrow C Stream ownership protocol and keep the plugin loaded.
pub unsafe fn open_reader<F: PartitionReaderFactory>(
task: *const abi::SparkDsTaskContext,
schema: SchemaRef,
state: &[u8],
partition: &[u8],
) -> Result<FFI_ArrowArrayStream> {
stream::validate_schema(&schema)?;
let factory: F = decode(state)?;
let (task, partition_index) = unsafe { TaskContext::from_raw(task)? };
let context = ReaderContext::new(schema.clone(), partition_index, task);
let reader = factory.open(decode(partition)?, context)?;
Ok(unsafe { stream::export(reader, &schema) })
}
fn require(capabilities: Capabilities, capability: Capabilities, operation: &str) -> Result<()> {
if capabilities.contains(capability) {
Ok(())
} else {
Err(format!("source does not support {operation}").into())
}
}
/// The builder of a scan that is not planned yet.
fn builder<B>(scan: &mut Option<B>) -> Result<&mut B> {
scan.as_mut()
.ok_or_else(|| "the scan has already been planned".into())
}
/// Encodes the factory of a plan, as the state of its reader, and each of its partitions.
fn encode_plan<F: PartitionReaderFactory>(plan: ScanPlan<F>) -> Result<EncodedPlan> {
Ok(EncodedPlan {
state: encode(&plan.factory)?,
partitions: plan.partitions.iter().map(encode).collect::<Result<_>>()?,
})
}
fn lock<T>(mutex: &Mutex<T>) -> MutexGuard<'_, T> {
// A provider panic becomes an ABI error. Recover the lock so close can
// still remove and release the handle after that failed call.
mutex.lock().unwrap_or_else(|error| error.into_inner())
}
fn get<T>(handles: &HandleMap<T>, handle: i64) -> Result<Arc<Mutex<T>>> {
lock(handles)
.get(&handle)
.cloned()
.ok_or_else(|| format!("unknown or closed native handle: {handle}").into())
}
fn remove<T>(handles: &HandleMap<T>, handle: i64) {
let value = lock(handles).remove(&handle);
// Provider destructors run after releasing the registry lock. Repeated
// closes are harmless, and IDs are never reused.
drop_provider(value);
}
struct SourceState<S> {
source: S,
capabilities: Capabilities,
}
/// Offsets are compact JSON on a single line, which Spark stores in the checkpoint as they
/// are, so they have no envelope: the library owns their format. JSON writes a NaN or an
/// infinite float as `null`, which does not decode as a float, so this decodes the JSON before
/// Spark uses or stores it: a restarted query would otherwise fail on that offset every time.
fn encode_offset<T: Serialize + DeserializeOwned>(offset: &T) -> Result<String> {
let json = serde_json::to_string(offset)?;
match serde_json::from_str::<T>(&json) {
Ok(_) => Ok(json),
Err(error) => {
let cause = "JSON writes NaN and infinite floats as null";
Err(format!("the returned offset {json} does not decode ({cause}): {error}").into())
}
}
}
fn decode_offset<T: DeserializeOwned>(json: &str) -> Result<T> {
serde_json::from_str(json)
.map_err(|error| format!("cannot decode the offset {json}: {error}").into())
}
/// The state of a reader or a writer, the partitions and the commit messages are MessagePack
/// in a versioned envelope. MessagePack is self-describing, and the SDK writes structs as maps
/// with the names of their fields, so the serde attributes that need them, such as `untagged`,
/// `flatten` and `default`, work, and floats, including NaN and the infinities, round-trip as
/// they are. A `Vec<u8>` stays a sequence: serde buffers the values of `untagged` and `flatten`
/// before deserializing them, and its buffer cannot read MessagePack binary as a sequence.
/// These values never outlive the application, and the same build of the library reads them,
/// so the format is an implementation detail; see the README.
#[derive(Serialize, Deserialize)]
struct Envelope<T> {
version: u32,
value: T,
}
pub(crate) fn encode<T: Serialize>(value: &T) -> Result<Vec<u8>> {
let mut bytes = Vec::new();
let mut serializer = rmp_serde::Serializer::new(&mut bytes).with_struct_map();
Envelope {
version: STATE_VERSION,
value,
}
.serialize(&mut serializer)?;
Ok(bytes)
}
pub(crate) fn decode<T: DeserializeOwned>(bytes: &[u8]) -> Result<T> {
let envelope: Envelope<T> = rmp_serde::from_slice(bytes)?;
if envelope.version != STATE_VERSION {
return Err(format!("unsupported native state version: {}", envelope.version).into());
}
Ok(envelope.value)
}
pub(crate) fn provider_call<T>(
action: impl FnOnce() -> Result<T>,
) -> std::result::Result<T, String> {
catch_unwind(AssertUnwindSafe(|| {
action().map_err(|error| describe(&*error))
}))
.unwrap_or_else(|payload| Err(panic_message(payload)))
}
pub(crate) fn drop_provider<T>(value: T) {
// Close has no error channel and must never unwind across the native ABI, so log the panic.
if let Err(payload) = catch_unwind(AssertUnwindSafe(|| drop(value))) {
// Outside the log call, which skips its arguments when WARN is off: panic_message must
// run to forget a payload whose drop could panic.
let message = panic_message(payload);
log::warn!("Ignoring a panic during a drop: {message}");
}
}
/// The message of an error followed by those of its sources, which `Display` of many
/// errors, such as those with added context, omits.
pub(crate) fn describe(error: &(dyn std::error::Error + 'static)) -> String {
let mut message = error.to_string();
let mut source = error.source();
while let Some(cause) = source {
let cause_message = cause.to_string();
if !message.contains(&cause_message) {
message.push_str(": ");
message.push_str(&cause_message);
}
source = cause.source();
}
message
}
pub(crate) fn panic_message(payload: Box<dyn Any + Send>) -> String {
let message = if let Some(message) = payload.downcast_ref::<String>() {
message.clone()
} else if let Some(message) = payload.downcast_ref::<&str>() {
(*message).to_owned()
} else {
// An arbitrary panic payload can itself panic when dropped.
std::mem::forget(payload);
return "native provider panicked with a non-string payload".to_owned();
};
format!("native provider panicked: {message}")
}
/// Error and log text is a C string. A provider message may contain embedded NULs.
pub(crate) fn c_message(message: String) -> CString {
CString::new(message.replace('\0', "\\0")).expect("NULs removed")
}
#[cfg(test)]
mod tests {
use std::sync::atomic::AtomicUsize;
use arrow_array::ffi_stream::ArrowArrayStreamReader;
use arrow_array::{Int64Array, RecordBatch};
use arrow_schema::{DataType, Field, Schema};
use super::*;
use crate::{PartitionReader, Unsupported};
#[derive(Clone, Copy)]
enum FailureMode {
None,
Error,
Panic,
}
impl FailureMode {
fn fail(self, message: &str) -> Result<()> {
match self {
Self::None => Ok(()),
Self::Error => Err(message.into()),
Self::Panic => panic!("{message}"),
}
}
}
struct Source {
builds: Arc<AtomicUsize>,
limits: Arc<AtomicUsize>,
drops: Arc<AtomicUsize>,
builder_drops: Arc<AtomicUsize>,
limit_support: LimitSupport,
failure: FailureMode,
}
impl Drop for Source {
fn drop(&mut self) {
self.drops.fetch_add(1, Ordering::SeqCst);
}
}
struct Builder {
builds: Arc<AtomicUsize>,
limits: Arc<AtomicUsize>,
drops: Arc<AtomicUsize>,
limit_support: LimitSupport,
failure: FailureMode,
value: u64,
}
impl Drop for Builder {
fn drop(&mut self) {
self.drops.fetch_add(1, Ordering::SeqCst);
}
}
impl DataSource for Source {
type ScanBuilder = Builder;
type MicroBatchStream = Unsupported;
type BatchWrite = Unsupported;
type StreamingWrite = Unsupported;
fn new(_: CreateInfo) -> Result<Self> {
Ok(Self {
builds: Arc::default(),
limits: Arc::default(),
drops: Arc::default(),
builder_drops: Arc::default(),
limit_support: LimitSupport::Unsupported,
failure: FailureMode::None,
})
}
fn infer_schema(&self) -> Result<SchemaRef> {
Ok(id_schema())
}
fn new_scan(&self, _: ScanInfo) -> Result<Builder> {
Ok(Builder {
builds: self.builds.clone(),
limits: self.limits.clone(),
drops: self.builder_drops.clone(),
limit_support: self.limit_support,
failure: self.failure,
value: 42,
})
}
}
#[derive(Serialize, Deserialize)]
struct Factory(u64);
impl PartitionReaderFactory for Factory {
type Partition = u64;
// Ignores the schema of the context, to test that the SDK checks it.
fn open<'task>(
&self,
partition: u64,
_: ReaderContext<'task>,
) -> Result<PartitionReader<'task>> {
let values = Arc::new(Int64Array::from(vec![(self.0 + partition) as i64]));
let batch = RecordBatch::try_new(id_schema(), vec![values])?;
Ok(Box::new(std::iter::once(Ok(batch))))
}
}
impl ScanBuilder for Builder {
type Factory = Factory;
fn push_limit(&mut self, limit: usize) -> Result<LimitSupport> {
self.limits.fetch_add(1, Ordering::SeqCst);
self.value = limit as u64;
self.failure.fail("negotiation failed")?;
Ok(self.limit_support)
}
fn plan(self) -> Result<ScanPlan<Factory>> {
self.builds.fetch_add(1, Ordering::SeqCst);
self.failure.fail("planning failed")?;
Ok(ScanPlan::new(Factory(self.value), vec![2, 7]))
}
}
fn id_schema() -> SchemaRef {
Arc::new(Schema::new(vec![Field::new("id", DataType::Int64, false)]))
}
fn info() -> CreateInfo {
CreateInfo::new("bridge_test", Default::default())
}
fn task(partition: i32, attempt: i32) -> abi::SparkDsTaskContext {
abi::SparkDsTaskContext {
size: std::mem::size_of::<abi::SparkDsTaskContext>() as i64,
stage_id: 1,
stage_attempt_number: 0,
partition_id: partition,
attempt_number: attempt,
task_attempt_id: i64::from(attempt) * 2 + i64::from(partition),
is_interrupted: None,
}
}
fn error_message<T>(result: Result<T>) -> String {
result
.err()
.expect("expected a provider failure")
.to_string()
}
#[test]
fn source_can_close_before_planning_and_a_scan_is_planned_once() {
let bridge = Bridge::<Source>::default();
let source = Source::new(info()).unwrap();
let builds = source.builds.clone();
let drops = source.drops.clone();
let builder_drops = source.builder_drops.clone();
let (handle, _) = bridge.register_source(source).unwrap();
let schema = bridge.schema(handle).unwrap();
let reader = bridge.create_reader(handle, schema).unwrap();
bridge.close_source(handle).unwrap();
bridge.close_source(handle).unwrap();
assert_eq!(drops.load(Ordering::SeqCst), 1);
assert!(bridge.schema(handle).is_err());
let plan = bridge.plan(reader).unwrap();
assert_eq!(decode::<u64>(&plan.partitions[0]).unwrap(), 2);
assert_eq!(decode::<u64>(&plan.partitions[1]).unwrap(), 7);
assert_eq!(decode::<Factory>(&plan.state).unwrap().0, 42);
assert_eq!(builds.load(Ordering::SeqCst), 1);
// Planning consumed the builder: no other call reaches it.
assert_eq!(builder_drops.load(Ordering::SeqCst), 1);
assert!(error_message(bridge.plan(reader)).contains("already been planned"));
assert!(bridge.prune_columns(reader, &[]).is_err());
bridge.close_reader(reader).unwrap();
assert!(bridge.plan(reader).is_err());
}
#[test]
fn only_global_limits_return_true_to_the_abi() {
for support in [LimitSupport::Unsupported, LimitSupport::Global] {
let bridge = Bridge::<Source>::default();
let mut source = Source::new(info()).unwrap();
source.limit_support = support;
let limits = source.limits.clone();
let (handle, _) = bridge.register_source(source).unwrap();
let reader = bridge
.create_reader(handle, bridge.schema(handle).unwrap())
.unwrap();
assert_eq!(
bridge.push_limit(reader, 4).unwrap(),
support == LimitSupport::Global
);
assert_eq!(limits.load(Ordering::SeqCst), 1);
}
}
#[test]
fn negotiation_and_planning_errors_and_panics_are_reported() {
for (failure, expected) in [
(FailureMode::Error, "failed"),
(FailureMode::Panic, "native provider panicked: "),
] {
let bridge = Bridge::<Source>::default();
let mut source = Source::new(info()).unwrap();
source.failure = failure;
let builds = source.builds.clone();
let drops = source.builder_drops.clone();
let (handle, _) = bridge.register_source(source).unwrap();
let schema = bridge.schema(handle).unwrap();
let negotiated = bridge.create_reader(handle, schema.clone()).unwrap();
let planned = bridge.create_reader(handle, schema).unwrap();
bridge.close_source(handle).unwrap();
let call = |action: &dyn Fn() -> Result<()>| {
let status = abi::call(action);
assert_ne!(status, 0);
let error = unsafe { std::ffi::CStr::from_ptr(abi::last_error()) };
error.to_str().unwrap().to_owned()
};
let error = call(&|| bridge.push_limit(negotiated, 1).map(drop));
assert!(error.contains(expected), "{error}");
assert!(error.contains("negotiation failed"), "{error}");
let error = call(&|| bridge.plan(planned).map(drop));
assert!(error.contains(expected), "{error}");
assert!(error.contains("planning failed"), "{error}");
assert_eq!(builds.load(Ordering::SeqCst), 1);
// The failed plan consumed its builder; Spark only closes the other scan.
assert_eq!(drops.load(Ordering::SeqCst), 1);
bridge.close_reader(negotiated).unwrap();
bridge.close_reader(planned).unwrap();
assert_eq!(drops.load(Ordering::SeqCst), 2);
}
}
#[test]
fn scans_of_one_source_keep_pushdown_and_plans_independent() {
let bridge = Bridge::<Source>::default();
let mut source = Source::new(info()).unwrap();
source.limit_support = LimitSupport::Global;
let builds = source.builds.clone();
let limits = source.limits.clone();
let (handle, _) = bridge.register_source(source).unwrap();
let first = bridge
.create_reader(handle, bridge.schema(handle).unwrap())
.unwrap();
let second = bridge
.create_reader(handle, bridge.schema(handle).unwrap())
.unwrap();
bridge.close_source(handle).unwrap();
assert!(bridge.push_limit(first, 5).unwrap());
let first_plan = bridge.plan(first).unwrap();
let second_plan = bridge.plan(second).unwrap();
assert_eq!(decode::<Factory>(&first_plan.state).unwrap().0, 5);
assert_eq!(decode::<Factory>(&second_plan.state).unwrap().0, 42);
assert_eq!(builds.load(Ordering::SeqCst), 2);
assert_eq!(limits.load(Ordering::SeqCst), 1);
bridge.close_reader(first).unwrap();
bridge.close_reader(second).unwrap();
}
#[test]
fn executor_retries_use_only_serialized_values_after_the_driver_is_dropped() {
let bridge = Bridge::<Source>::default();
let source = Source::new(info()).unwrap();
let builds = source.builds.clone();
let source_drops = source.drops.clone();
let builder_drops = source.builder_drops.clone();
let (handle, _) = bridge.register_source(source).unwrap();
let reader = bridge.create_reader(handle, id_schema()).unwrap();
bridge.close_source(handle).unwrap();
// Model Spark copying the factory and partition descriptors out of the plugin.
let EncodedPlan { state, partitions } = bridge.plan(reader).unwrap();
bridge.close_reader(reader).unwrap();
drop(bridge);
assert_eq!(builds.load(Ordering::SeqCst), 1);
assert_eq!(source_drops.load(Ordering::SeqCst), 1);
assert_eq!(builder_drops.load(Ordering::SeqCst), 1);
for attempt in 0..2 {
for (index, partition) in partitions.iter().enumerate() {
let task = task(index as i32, attempt);
// The executor entry point depends only on Factory, not Source or Builder.
let stream =
unsafe { open_reader::<Factory>(&task, id_schema(), &state, partition) }
.unwrap();
let mut reader = ArrowArrayStreamReader::try_new(stream).unwrap();
let batch = reader.next().unwrap().unwrap();
let ids = batch
.column(0)
.as_any()
.downcast_ref::<Int64Array>()
.unwrap();
assert_eq!(ids.values(), &[42 + [2, 7][index]]);
assert!(reader.next().is_none());
}
}
}
#[test]
fn reader_partition_indices_are_independent_of_task_identity() {
#[derive(Serialize, Deserialize)]
struct ContextFactory;
impl PartitionReaderFactory for ContextFactory {
type Partition = ();
fn open<'task>(
&self,
_: (),
context: ReaderContext<'task>,
) -> Result<PartitionReader<'task>> {
let task = context.task;
let values = Arc::new(Int64Array::from(vec![
i64::from(context.partition_index),
i64::from(task.stage_id()),
i64::from(task.stage_attempt_number()),
i64::from(task.attempt_number()),
task.task_attempt_id(),
]));
let batch = RecordBatch::try_new(id_schema(), vec![values])?;
Ok(Box::new(std::iter::once(Ok(batch))))
}
}
let state = encode(&ContextFactory).unwrap();
let partition = encode(&()).unwrap();
for index in [3, 9] {
// A coalesced task can read several scan partitions under the same task identity.
let mut host = task(index, 2);
host.task_attempt_id = 42;
let stream =
unsafe { open_reader::<ContextFactory>(&host, id_schema(), &state, &partition) }
.unwrap();
let mut reader = ArrowArrayStreamReader::try_new(stream).unwrap();
let batch = reader.next().unwrap().unwrap();
let values = batch
.column(0)
.as_any()
.downcast_ref::<Int64Array>()
.unwrap();
assert_eq!(values.values(), &[i64::from(index), 1, 0, 2, 42]);
assert!(reader.next().is_none());
}
}
#[test]
fn executor_rejects_batches_that_do_not_have_the_schema_to_read() {
let bridge = Bridge::<Source>::default();
let (handle, _) = bridge.create(info()).unwrap();
let reader = bridge
.create_reader(handle, bridge.schema(handle).unwrap())
.unwrap();
let plan = bridge.plan(reader).unwrap();
bridge.close_reader(reader).unwrap();
bridge.close_source(handle).unwrap();
drop(bridge);
// The factory returns a bigint id column, but Spark reads a string id or a label.
for (schema, expected) in [
(DataType::Utf8, "does not match the schema to read"),
(DataType::Int64, "without the column label"),
] {
let name = if schema == DataType::Utf8 {
"id"
} else {
"label"
};
let schema = Arc::new(Schema::new(vec![Field::new(name, schema, false)]));
let task = task(0, 0);
let mut stream =
unsafe { open_reader::<Factory>(&task, schema, &plan.state, &plan.partitions[0]) }
.unwrap();
// get_schema reads the first batch, which does not have the schema to read.
let mut schema = arrow_schema::ffi::FFI_ArrowSchema::empty();
assert_ne!(
unsafe { stream.get_schema.unwrap()(&mut stream, &mut schema) },
0
);
let error =
unsafe { std::ffi::CStr::from_ptr(stream.get_last_error.unwrap()(&mut stream)) };
let error = error.to_str().unwrap();
assert!(error.contains(expected), "{error}");
}
}
#[test]
fn capabilities_keep_only_implemented_operations() {
struct Narrowing(Capabilities);
impl DataSource for Narrowing {
type ScanBuilder = Builder;
type MicroBatchStream = Unsupported;
type BatchWrite = Unsupported;
type StreamingWrite = Unsupported;
fn new(_: CreateInfo) -> Result<Self> {
unreachable!("registered directly")
}
fn capabilities(&self) -> Capabilities {
self.0
}
}
let bridge = Bridge::<Narrowing>::default();
for (declared, expected) in [
(Capabilities::all(), abi::BATCH_READ),
(Capabilities::empty(), 0),
(Capabilities::all().without(Capabilities::BATCH_READ), 0),
] {
let (handle, mask) = bridge.register_source(Narrowing(declared)).unwrap();
assert_eq!(mask, expected, "{declared:?}");
bridge.close_source(handle).unwrap();
}
}
#[test]
fn writes_truncate_only_when_they_declare_it() {
use crate::{AbortInfo, CommitInfo, StreamingAbortInfo, StreamingCommitInfo};
// Writes that keep the default SUPPORTS_TRUNCATE, which these tests never create.
struct AppendOnly;
impl BatchWrite for AppendOnly {
type Factory = Unsupported;
type Message = Unsupported;
fn new_writer_factory(&self) -> Result<Unsupported> {
unreachable!("not created")
}
fn commit(&mut self, _: CommitInfo<Unsupported>) -> Result<()> {
unreachable!("not created")
}
fn abort(&mut self, _: AbortInfo<Unsupported>) -> Result<()> {
unreachable!("not created")
}
}
impl StreamingWrite for AppendOnly {
type Factory = Unsupported;
type Message = Unsupported;
fn new_writer_factory(&self) -> Result<Unsupported> {
unreachable!("not created")
}
fn commit(&mut self, _: StreamingCommitInfo<Unsupported>) -> Result<()> {
unreachable!("not created")
}
fn abort(&mut self, _: StreamingAbortInfo<Unsupported>) -> Result<()> {
unreachable!("not created")
}
}
struct Appending;
impl DataSource for Appending {
type ScanBuilder = Unsupported;
type MicroBatchStream = Unsupported;
type BatchWrite = AppendOnly;
type StreamingWrite = AppendOnly;
fn new(_: CreateInfo) -> Result<Self> {
unreachable!("registered directly")
}
}
let bridge = Bridge::<Appending>::default();
let (handle, mask) = bridge.register_source(Appending).unwrap();
assert_eq!(mask, abi::BATCH_WRITE | abi::STREAMING_WRITE);
for (query_id, mode) in [
(None, "the save mode overwrite"),
(Some("query".to_owned()), "the output mode complete"),
] {
let created = bridge.create_writer(handle, id_schema(), WriteMode::Truncate, query_id);
let error = error_message(created);
assert!(error.contains(mode), "{error}");
}
bridge.close_source(handle).unwrap();
}
#[test]
fn non_string_panic_payloads_do_not_escape() {
struct PanicsOnDrop;
impl Drop for PanicsOnDrop {
fn drop(&mut self) {
panic!("the payload panicked when dropped");
}
}
struct DropsWithPanic;
impl Drop for DropsWithPanic {
fn drop(&mut self) {
std::panic::panic_any(PanicsOnDrop);
}
}
let expected = "native provider panicked with a non-string payload";
let error = provider_call::<()>(|| std::panic::panic_any(42));
assert_eq!(error.unwrap_err(), expected);
let error = provider_call::<()>(|| std::panic::panic_any(PanicsOnDrop));
assert_eq!(error.unwrap_err(), expected);
// Neither the drop nor its payload unwinds out of drop_provider.
drop_provider(DropsWithPanic);
}
#[test]
fn error_messages_include_their_sources_once() {
#[derive(Debug)]
struct Context(std::io::Error);
impl std::fmt::Display for Context {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter.write_str("cannot open the table")
}
}
impl std::error::Error for Context {
fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
Some(&self.0)
}
}
let cause = std::io::Error::new(std::io::ErrorKind::NotFound, "no such file");
let error: crate::Error = Box::new(Context(cause));
assert_eq!(describe(&*error), "cannot open the table: no such file");
let error = provider_call::<()>(|| Err(Box::new(Context(std::io::Error::other("io")))));
assert_eq!(error.unwrap_err(), "cannot open the table: io");
// A message that already contains its source is not repeated.
let arrow = arrow_schema::ArrowError::ExternalError(Box::new(std::io::Error::other("io")));
assert_eq!(describe(&arrow), arrow.to_string());
}
#[test]
fn rejects_a_different_wire_version() {
let other = rmp_serde::to_vec_named(&Envelope {
version: STATE_VERSION + 1,
value: 42_u64,
})
.unwrap();
let error = decode::<u64>(&other).unwrap_err();
assert!(error
.to_string()
.contains("unsupported native state version"));
assert_eq!(decode::<u64>(&encode(&42_u64).unwrap()).unwrap(), 42);
}
#[test]
fn offsets_that_do_not_decode_from_their_json_are_rejected() {
#[derive(Serialize, Deserialize, Debug, PartialEq)]
struct Offset {
next: u64,
rate: f64,
}
// Returns an offset with its rate from both calls that return an offset to Spark.
struct Rates(f64);
impl MicroBatchStream for Rates {
type Offset = Offset;
type Factory = Factory;
fn initial_offset(&mut self) -> Result<Offset> {
Ok(Offset {
next: 10,
rate: self.0,
})
}
fn latest_offset(&mut self, _: LatestOffsetInfo<Offset>) -> Result<Offset> {
self.initial_offset()
}
fn plan(&mut self, _: MicroBatchInfo<Offset>) -> Result<ScanPlan<Factory>> {
unreachable!("not planned")
}
}
struct Streaming(f64);
impl DataSource for Streaming {
type ScanBuilder = Unsupported;
type MicroBatchStream = Rates;
type BatchWrite = Unsupported;
type StreamingWrite = Unsupported;
fn new(_: CreateInfo) -> Result<Self> {
unreachable!("registered directly")
}
fn new_micro_batch_stream(&self, _: MicroBatchStreamInfo) -> Result<Rates> {
Ok(Rates(self.0))
}
}
let offset = Offset {
next: 10,
rate: 0.5,
};
let json = encode_offset(&offset).unwrap();
assert_eq!(json, r#"{"next":10,"rate":0.5}"#);
assert_eq!(decode_offset::<Offset>(&json).unwrap(), offset);
// JSON writes a NaN or an infinite float as null, which does not decode as an f64.
let expected = r#"offset {"next":10,"rate":null} does not decode"#;
for rate in [f64::NAN, f64::INFINITY, f64::NEG_INFINITY] {
let bridge = Bridge::<Streaming>::default();
let (handle, _) = bridge.register_source(Streaming(rate)).unwrap();
let info = MicroBatchStreamInfo::new(id_schema(), "file:/tmp/checkpoint/sources/0");
let stream = bridge.create_stream_reader(handle, info).unwrap();
bridge.close_source(handle).unwrap();
let initial = error_message(bridge.initial_offset(stream));
assert!(initial.contains(expected), "{initial}");
let latest = bridge.latest_offset(stream, LatestOffsetInfo::new(json.clone()));
let latest = error_message(latest);
assert!(latest.contains(expected), "{latest}");
bridge.close_stream_reader(stream).unwrap();
}
}
#[test]
fn state_keeps_floats_and_bytes_and_supports_self_describing_serde_attributes() {
#[derive(Serialize, Deserialize, Debug, PartialEq)]
#[serde(untagged)]
enum Split {
Rows { first: i64 },
Files { paths: Vec<String>, footer: Vec<u8> },
}
#[derive(Serialize, Deserialize, Debug, PartialEq)]
struct Statistics {
min: f64,
#[serde(default, skip_serializing_if = "Option::is_none")]
max: Option<f64>,
sketch: Vec<u8>,
}
#[derive(Serialize, Deserialize, Debug, PartialEq)]
struct Partition {
footer: Vec<u8>,
split: Split,
#[serde(flatten)]
statistics: Statistics,
}
let partition = Partition {
footer: (0..=255).collect(),
// Serde buffers the values of untagged enums and flattened fields.
split: Split::Files {
paths: vec!["a".into()],
footer: vec![1, 2],
},
statistics: Statistics {
min: f64::NEG_INFINITY,
max: Some(f64::NAN),
sketch: vec![255, 0],
},
};
let decoded: Partition = decode(&encode(&partition).unwrap()).unwrap();
assert_eq!(decoded.footer, partition.footer);
assert_eq!(decoded.split, partition.split);
assert_eq!(decoded.statistics.min, f64::NEG_INFINITY);
assert!(decoded.statistics.max.unwrap().is_nan());
assert_eq!(decoded.statistics.sketch, partition.statistics.sketch);
}
}