hyprstream_decision_stub/
flight.rs1use 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
56pub const STATE_PARAMETER: &str = "state";
58
59struct PreparedDecide {
61 set: QuestionSet,
62 decision_schema: DecisionSchema,
63 triple: VersionTriple,
64 states: Vec<String>,
66}
67
68#[derive(Default)]
70pub struct DecideFlightSqlService {
71 statements: Mutex<HashMap<Vec<u8>, PreparedDecide>>,
72}
73
74impl DecideFlightSqlService {
75 pub fn into_server(self) -> arrow_flight::flight_service_server::FlightServiceServer<Self> {
77 arrow_flight::flight_service_server::FlightServiceServer::new(self)
78 }
79
80 #[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; 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 pub fn parameter_schema() -> Schema {
155 Schema::new(vec![Field::new(STATE_PARAMETER, DataType::Utf8, false)])
156 }
157
158 #[allow(clippy::result_large_err)] 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
171fn 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(¶meter_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 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 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
345pub 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
364pub fn decide_document(questions_json: &str, schema_version: &str) -> String {
366 format!(r#"{{"schema_version": "{schema_version}", "questions": {questions_json}}}"#)
367}