Skip to main content

hyprstream_decision_stub/
flight.rs

1//! The P3.5 `decide` contract, stubbed: Flight SQL prepared statements that pin a
2//! question set plus the (schema, model, calib) version triple, bind batches of states,
3//! and return `DecisionSchema`-conformant Arrow batches.
4//!
5//! Contract shape (what P3.5 will implement for real on `hyprstream-flight`):
6//!
7//! - **Create**: `CreatePreparedStatement` whose query text is a JSON *decide document*:
8//!   `{"questions": {…jev-1 question map…}, "schema_version": "…", "calib_version": …,
9//!   "model": "…"}`. `schema_version` is required (the triple is pinned at prepare time,
10//!   per P3.5); `model` defaults to the stub alias and resolves to the versioned id;
11//!   `calib_version` may be null (uncalibrated). The returned handle is the blake3 hash
12//!   of the canonical decide document, so identical documents share a statement.
13//! - **Parameter schema**: a single non-null `state: utf8` column — `decide(schema,
14//!   batch)` where the batch is one state per row.
15//! - **Dataset schema**: the P0.1a `DecisionSchema` Arrow schema — per-question
16//!   `fixed_size_list<f32>` probabilities with `jev.kind`/`jev.labels` field metadata,
17//!   label, reserved conformal-set column, and the version-triple columns.
18//! - **Drift fails loudly**: an unknown (or closed) handle is `not_found`; a decide
19//!   document whose question ids are not identifier-safe for the columnar surface is
20//!   `invalid_argument` at create time (P0.1a's Arrow contract).
21//! - **Execute**: bound states are mock-answered row by row and emitted as one
22//!   `RecordBatch` via `DecisionSchema::build_batch` — producer tolerance (D5) enforced
23//!   by construction.
24
25use std::collections::HashMap;
26use std::sync::Arc;
27
28use parking_lot::Mutex;
29
30use arrow_array::Array as _;
31use arrow_array::{ArrayRef, StringArray};
32use arrow_flight::encode::FlightDataEncoderBuilder;
33use arrow_flight::sql::server::{FlightSqlService, PeekableFlightDataStream};
34use arrow_flight::sql::{
35    ActionClosePreparedStatementRequest, ActionCreatePreparedStatementRequest,
36    ActionCreatePreparedStatementResult, CommandPreparedStatementQuery,
37    DoPutPreparedStatementResult, ProstMessageExt, SqlInfo,
38};
39use arrow_flight::utils::flight_data_to_arrow_batch;
40use arrow_flight::{
41    Action, FlightDescriptor, FlightEndpoint, FlightInfo, IpcMessage, SchemaAsIpc, Ticket,
42};
43use arrow_ipc::writer::IpcWriteOptions;
44use arrow_schema::{DataType, Field, Schema, SchemaRef};
45use futures::{StreamExt, TryStreamExt};
46use hyprstream_decision::answer::VersionTriple;
47use hyprstream_decision::arrow::DecisionSchema;
48use hyprstream_decision::author;
49use hyprstream_decision::entry::Entry;
50use hyprstream_decision::spec::QuestionSet;
51use prost::Message;
52use tonic::{Request, Response, Status};
53
54use crate::mock::{MockDecisionModel, STUB_MODEL_VERSION};
55
56/// Name of the single parameter column: one state per row of the bound batch.
57pub const STATE_PARAMETER: &str = "state";
58
59/// One pinned prepared `decide` statement.
60struct PreparedDecide {
61    set: QuestionSet,
62    decision_schema: DecisionSchema,
63    triple: VersionTriple,
64    /// States bound via DoPut, one per parameter row.
65    states: Vec<String>,
66}
67
68/// The stub Flight SQL service. Stateless apart from the prepared-statement table.
69#[derive(Default)]
70pub struct DecideFlightSqlService {
71    statements: Mutex<HashMap<Vec<u8>, PreparedDecide>>,
72}
73
74impl DecideFlightSqlService {
75    /// A tonic service wrapping this stub, for `Server::builder().add_service(…)`.
76    pub fn into_server(self) -> arrow_flight::flight_service_server::FlightServiceServer<Self> {
77        arrow_flight::flight_service_server::FlightServiceServer::new(self)
78    }
79
80    /// Parse and validate a decide document, returning the pinned statement parts.
81    // tonic::Status is the trait-mandated Err; boxing it would fight the Flight SQL API.
82    #[allow(clippy::result_large_err)]
83    fn prepare(query: &str) -> Result<(QuestionSet, DecisionSchema, VersionTriple), Status> {
84        let entry: Entry = serde_json::from_str(query).map_err(|error| {
85            Status::invalid_argument(format!("decide document is not valid JSON: {error}"))
86        })?;
87        let Entry::Map(fields) = &entry else {
88            return Err(Status::invalid_argument(
89                "decide document must be a JSON object: {questions, schema_version, calib_version?, model?}",
90            ));
91        };
92        let mut questions = None;
93        let mut schema_version = None;
94        let mut calib_version = None;
95        let mut model = None;
96        for (key, value) in fields {
97            match key.as_str() {
98                "questions" => questions = Some(value.clone()),
99                "schema_version" => match value {
100                    Entry::Str(version) => schema_version = Some(version.clone()),
101                    _ => {
102                        return Err(Status::invalid_argument(
103                            "`schema_version` must be a string",
104                        ))
105                    }
106                },
107                "calib_version" => match value {
108                    Entry::Null => calib_version = Some(None),
109                    Entry::Str(version) => calib_version = Some(Some(version.clone())),
110                    _ => {
111                        return Err(Status::invalid_argument(
112                            "`calib_version` must be a string or null",
113                        ))
114                    }
115                },
116                "model" => match value {
117                    Entry::Str(name) => model = Some(name.clone()),
118                    _ => return Err(Status::invalid_argument("`model` must be a string")),
119                },
120                other => {
121                    return Err(Status::invalid_argument(format!(
122                        "unknown decide-document field `{other}`; expected `questions`, `schema_version`, `calib_version`, `model`"
123                    )));
124                }
125            }
126        }
127        let questions = questions.ok_or_else(|| {
128            Status::invalid_argument("decide document requires a `questions` map")
129        })?;
130        let schema_version = schema_version.ok_or_else(|| {
131            Status::invalid_argument(
132                "decide document requires `schema_version`: prepared statements pin the (schema, model, calib) version triple",
133            )
134        })?;
135        let _requested = model; // every alias resolves to the stub's versioned id
136
137        let document = Entry::Map(vec![("questions".to_owned(), questions)]);
138        let set = author::parse_json(&document.canonical_text())
139            .map_err(|error| Status::invalid_argument(format!("invalid question set: {error}")))?;
140        let decision_schema = DecisionSchema::from_question_set(&set).map_err(|error| {
141            Status::invalid_argument(format!(
142                "question set is not usable on the columnar surface: {error}"
143            ))
144        })?;
145        let triple = VersionTriple {
146            schema: schema_version,
147            model: STUB_MODEL_VERSION.to_owned(),
148            calib: calib_version.flatten(),
149        };
150        Ok((set, decision_schema, triple))
151    }
152
153    /// The `decide` parameter schema: one non-null `state` utf8 column.
154    pub fn parameter_schema() -> Schema {
155        Schema::new(vec![Field::new(STATE_PARAMETER, DataType::Utf8, false)])
156    }
157
158    #[allow(clippy::result_large_err)] // tonic::Status is the trait-mandated Err
159    fn statement(&self, handle: &[u8]) -> Result<(), Status> {
160        let statements = self.statements.lock();
161        if statements.contains_key(handle) {
162            Ok(())
163        } else {
164            Err(Status::not_found(
165                "unknown prepared statement handle (stale or drifted; re-prepare)",
166            ))
167        }
168    }
169}
170
171/// IPC-encapsulated schema bytes for prepared-statement results.
172fn schema_ipc(schema: &Schema) -> bytes::Bytes {
173    let IpcMessage(bytes) = SchemaAsIpc::new(schema, &IpcWriteOptions::default())
174        .try_into()
175        .unwrap_or_else(|error| {
176            panic!("schema IPC encoding is infallible for in-memory schemas: {error}")
177        });
178    bytes
179}
180
181#[tonic::async_trait]
182impl FlightSqlService for DecideFlightSqlService {
183    type FlightService = Self;
184
185    async fn register_sql_info(&self, _id: i32, _info: &SqlInfo) {}
186
187    async fn do_action_create_prepared_statement(
188        &self,
189        query: ActionCreatePreparedStatementRequest,
190        _request: Request<Action>,
191    ) -> Result<ActionCreatePreparedStatementResult, Status> {
192        let (set, decision_schema, triple) = Self::prepare(&query.query)?;
193        let handle = blake3::hash(query.query.as_bytes()).as_bytes().to_vec();
194        let dataset_schema = decision_schema.arrow_schema();
195        let parameter_schema = Self::parameter_schema();
196        let prepared = PreparedDecide {
197            set,
198            decision_schema,
199            triple,
200            states: Vec::new(),
201        };
202        self.statements.lock().insert(handle.clone(), prepared);
203        Ok(ActionCreatePreparedStatementResult {
204            prepared_statement_handle: handle.into(),
205            dataset_schema: schema_ipc(&dataset_schema),
206            parameter_schema: schema_ipc(&parameter_schema),
207        })
208    }
209
210    async fn do_action_close_prepared_statement(
211        &self,
212        query: ActionClosePreparedStatementRequest,
213        _request: Request<Action>,
214    ) -> Result<(), Status> {
215        self.statement(&query.prepared_statement_handle)?;
216        self.statements
217            .lock()
218            .remove(&query.prepared_statement_handle[..]);
219        Ok(())
220    }
221
222    async fn get_flight_info_prepared_statement(
223        &self,
224        query: CommandPreparedStatementQuery,
225        _request: Request<FlightDescriptor>,
226    ) -> Result<Response<FlightInfo>, Status> {
227        let statements = self.statements.lock();
228        let prepared = statements
229            .get(&query.prepared_statement_handle[..])
230            .ok_or_else(|| {
231                Status::not_found(
232                    "unknown prepared statement handle (stale or drifted; re-prepare)",
233                )
234            })?;
235        let schema = prepared.decision_schema.arrow_schema();
236        // The Flight SQL do_get dispatcher routes on the ticket's Any-encoded command,
237        // so the ticket carries the handle wrapped in CommandPreparedStatementQuery.
238        let command = CommandPreparedStatementQuery {
239            prepared_statement_handle: query.prepared_statement_handle.clone(),
240        };
241        let ticket = Ticket {
242            ticket: command.as_any().encode_to_vec().into(),
243        };
244        let info = FlightInfo::new()
245            .try_with_schema(&schema)
246            .map_err(|error| Status::internal(format!("schema encode failed: {error}")))?
247            .with_endpoint(FlightEndpoint::new().with_ticket(ticket))
248            .with_total_records(-1)
249            .with_ordered(false);
250        Ok(Response::new(info))
251    }
252
253    async fn do_put_prepared_statement_query(
254        &self,
255        query: CommandPreparedStatementQuery,
256        request: Request<PeekableFlightDataStream>,
257    ) -> Result<DoPutPreparedStatementResult, Status> {
258        self.statement(&query.prepared_statement_handle)?;
259        let parameter_schema = Arc::new(Self::parameter_schema());
260        let mut stream = request.into_inner();
261        let dictionaries: HashMap<i64, ArrayRef> = HashMap::new();
262        let mut states = Vec::new();
263        while let Some(data) = stream.next().await {
264            let data = data?;
265            // The DoPut stream opens with a Schema message; only record-batch messages
266            // carry parameter rows.
267            let header_type = arrow_ipc::root_as_message(&data.data_header[..])
268                .map_err(|error| Status::invalid_argument(format!("parameter message: {error}")))?
269                .header_type();
270            if header_type != arrow_ipc::MessageHeader::RecordBatch {
271                continue;
272            }
273            let batch = flight_data_to_arrow_batch(&data, parameter_schema.clone(), &dictionaries)
274                .map_err(|error| Status::invalid_argument(format!("parameter batch: {error}")))?;
275            let column = batch
276                .column_by_name(STATE_PARAMETER)
277                .and_then(|column| column.as_any().downcast_ref::<StringArray>())
278                .ok_or_else(|| {
279                    Status::invalid_argument(
280                        "parameter batch must carry a non-null utf8 `state` column",
281                    )
282                })?;
283            for row in 0..column.len() {
284                if column.is_null(row) {
285                    return Err(Status::invalid_argument(format!(
286                        "parameter row {row}: state must not be null"
287                    )));
288                }
289                states.push(column.value(row).to_owned());
290            }
291        }
292        let mut statements = self.statements.lock();
293        let prepared = statements
294            .get_mut(&query.prepared_statement_handle[..])
295            .ok_or_else(|| Status::not_found("statement closed while binding"))?;
296        prepared.states.extend(states);
297        Ok(DoPutPreparedStatementResult {
298            prepared_statement_handle: None,
299        })
300    }
301
302    async fn do_get_prepared_statement(
303        &self,
304        query: CommandPreparedStatementQuery,
305        _request: Request<Ticket>,
306    ) -> Result<
307        Response<<Self as arrow_flight::flight_service_server::FlightService>::DoGetStream>,
308        Status,
309    > {
310        let (set, schema, triple, states) = {
311            let statements = self.statements.lock();
312            let prepared = statements
313                .get(&query.prepared_statement_handle[..])
314                .ok_or_else(|| {
315                    Status::not_found(
316                        "unknown prepared statement handle (stale or drifted; re-prepare)",
317                    )
318                })?;
319            (
320                prepared.set.clone(),
321                prepared.decision_schema.clone(),
322                prepared.triple.clone(),
323                prepared.states.clone(),
324            )
325        };
326        let mock = MockDecisionModel;
327        let rows: Vec<_> = states
328            .iter()
329            .enumerate()
330            .map(|(row, state)| mock.answer_row(&set, state, row))
331            .collect();
332        let batch = schema
333            .build_batch(&triple, &rows)
334            .map_err(|error| Status::internal(format!("decision batch failed: {error}")))?;
335        let schema_ref: SchemaRef = Arc::new(schema.arrow_schema());
336        let stream = futures::stream::once(async move { Ok(batch) });
337        let encoded = FlightDataEncoderBuilder::new()
338            .with_schema(schema_ref)
339            .build(stream)
340            .map_err(Status::from);
341        Ok(Response::new(Box::pin(encoded)))
342    }
343}
344
345/// Serve the stub Flight SQL endpoint on `listener` in the background.
346pub async fn serve(
347    listener: std::net::TcpListener,
348) -> std::io::Result<(std::net::SocketAddr, tokio::task::JoinHandle<()>)> {
349    listener.set_nonblocking(true)?;
350    let address = listener.local_addr()?;
351    let handle = tokio::spawn(async move {
352        let listener = tokio::net::TcpListener::from_std(listener)
353            .unwrap_or_else(|error| panic!("tokio listener: {error}"));
354        let incoming = tokio_stream::wrappers::TcpListenerStream::new(listener);
355        tonic::transport::Server::builder()
356            .add_service(DecideFlightSqlService::default().into_server())
357            .serve_with_incoming(incoming)
358            .await
359            .unwrap_or_else(|error| panic!("flight server: {error}"));
360    });
361    Ok((address, handle))
362}
363
364/// Standalone decide-document builder used by tests and the SDK-less contract check.
365pub fn decide_document(questions_json: &str, schema_version: &str) -> String {
366    format!(r#"{{"schema_version": "{schema_version}", "questions": {questions_json}}}"#)
367}