Add ocs_doc_api: object-oriented CAD entity API (v2)

New crate crates/ocs_doc_api: object-centric facade (DocApi -> Document ->
collections -> typed handles), transport-agnostic wire layer (DocApiEnvelope =
single op | read-only query batch), per-op autocommit (no write transactions),
bulk ops with upfront-validation all-or-nothing, structured ApiError, and
build-time codegen (spec/entities.toml -> ops/query enums, api_reference.md,
binding_schema.json).

ocs_plugin_api: append-only PluginRequest::DocApiRequest / PluginResponse::
DocApiResponse (serde_bytes payload) + defaulted HostApi::doc_api_dispatch.

Host: DocApiBackend impl for HostSession (src/app/doc_api.rs) mapping to scene
primitives (solid_models lift-on-miss, register_prepared_solid_model, meshes
metrics), entity conversions (doc_api_convert.rs), HostSession accessors +
doc_api_dispatch override.

Tests: 592 host lib (incl. 7 DocApi integration tests: create/boolean/query,
unknown-id, transform-many all-or-nothing, query-batch cap, 2D/geometric/DWG
roundtrips), 8 crate unit tests. Examples + README/ARCHITECTURE/IMPLEMENTATION docs.
This commit is contained in:
Sebastian committed 2026-09-06 00:15:27 +02:00
1 parent 9129c85f97
commit e41086b058
44 files changed
+4837 -12

No files matched your search

@@ -0,0 +1,42 @@
//! In-process transport (plan §7): drives a `DocApiBackend` directly, inline.
//! Used by in-tree/built-in plugins and host tests. Thread-safe via a mutex so
//! many handles across many threads share it (calls are serialized).
use std::sync::Mutex;
use crate::backend::DocApiBackend;
use crate::envelope::{DocApiEnvelope, EnvelopeBody, Receipt};
use crate::error::ApiResult;
use crate::executor;
use crate::transport::Transport;
/// In-process transport: holds the backend behind a mutex (reentrant `&self`).
pub struct InProcess<B: DocApiBackend> {
backend: Mutex<B>,
}
impl<B: DocApiBackend> InProcess<B> {
pub fn new(backend: B) -> Self {
Self { backend: Mutex::new(backend) }
}
/// Borrow the backend mutably (test/introspection helper).
pub fn backend_mut(&mut self) -> &mut B {
self.backend.get_mut().expect("in-process backend poisoned")
}
/// Borrow the backend immutably (test/introspection helper).
pub fn backend(&self) -> std::sync::MutexGuard<'_, B> {
self.backend.lock().expect("in-process backend poisoned")
}
}
impl<B: DocApiBackend + Send> Transport for InProcess<B> {
fn apply(&self, req: DocApiEnvelope) -> ApiResult<Receipt> {
let mut backend = self.backend.lock().map_err(|_| {
crate::error::ApiError::Transport("in-process backend poisoned".into())
})?;
match req.body {
EnvelopeBody::Op(op) => executor::apply_op(&mut *backend, op),
EnvelopeBody::Queries(queries) => executor::apply_queries(&mut *backend, queries),
}
}
}
+55
View File
@@ -0,0 +1,55 @@
//! IPC transport (plan §7, decision #10): serializes `DocApiEnvelope` into the
//! append-only `PluginRequest::DocApiRequest { tab_id, bytes }` variant and ships
//! it through the plugin's `PluginRequestSender`. The host routes that variant to
//! the same crate executor (`ocs_doc_api::executor`) — one implementation.
use std::sync::Arc;
use ocs_plugin_api::host::{PluginRequestError, PluginRequestSender};
use ocs_plugin_api::ipc::protocol::{PluginRequest, PluginResponse};
use crate::envelope::{DocApiEnvelope, Receipt};
use crate::error::{ApiError, ApiResult};
use crate::transport::Transport;
/// Out-of-process IPC transport over the `ocs_plugin_api` channel. `Send + Sync`;
/// the underlying `PluginRequestSender` already serializes + correlates (V4).
pub struct OcsPluginApiIpc {
sender: Arc<dyn PluginRequestSender>,
tab_id: u64,
}
impl OcsPluginApiIpc {
pub fn new(sender: Arc<dyn PluginRequestSender>, tab_id: u64) -> Self {
Self { sender, tab_id }
}
fn transport_err(e: PluginRequestError) -> ApiError {
ApiError::Transport(e.0)
}
}
impl Transport for OcsPluginApiIpc {
fn apply(&self, req: DocApiEnvelope) -> ApiResult<Receipt> {
let bytes = bincode::serialize(&req)
.map_err(|e| ApiError::Transport(format!("envelope serialize: {e}")))?;
let resp = self
.sender
.request(PluginRequest::DocApiRequest { tab_id: self.tab_id, bytes })
.map_err(Self::transport_err)?;
match resp {
PluginResponse::DocApiResponse { bytes } => {
// The host serializes `ApiResult<Receipt>` so op/query errors
// (validation, geometry, unknown id) surface as the SAME
// structured `ApiError` the in-process executor produced.
let result: ApiResult<Receipt> = bincode::deserialize(&bytes)
.map_err(|e| ApiError::Transport(format!("receipt deserialize: {e}")))?;
result
}
PluginResponse::Error(msg) => Err(ApiError::Transport(msg)),
other => Err(ApiError::Transport(format!(
"unexpected DocApi response variant: {other:?}"
))),
}
}
}
+36
View File
@@ -0,0 +1,36 @@
//! The transport boundary (plan §7) — the ONLY plugin↔host boundary.
//!
//! Portability contract (SPSC / flume / shared-memory safe): a transport impl
//! must (a) accept `&self` calls from many threads and serialize sends internally,
//! (b) demultiplex responses to the right caller by a correlation id, (c)
//! block-with-timeout, (d) expose liveness. This matches the existing V4 channel
//! shape, so swapping socket → shm changes only the impl, never the facade.
#[cfg(feature = "host")]
pub mod inproc;
#[cfg(feature = "ipc")]
pub mod ipc;
#[cfg(feature = "host")]
pub use inproc::InProcess;
#[cfg(feature = "ipc")]
pub use ipc::OcsPluginApiIpc;
use crate::envelope::{DocApiEnvelope, Receipt};
use crate::error::ApiResult;
/// The only plugin↔host boundary. Object-centric: one method per unit of work —
/// a single write op, or a query batch. `&self` + `Send + Sync` so many entity
/// handles across many threads share one transport concurrently.
pub trait Transport: Send + Sync {
/// Apply `req` (ONE write op, or a query batch) and return its `Receipt`.
/// A write request carries exactly one `Operation`; a read request carries
/// one-or-more `Query` items (read-only batching is safe). Blocks up to an
/// internal timeout. Reentrant: safe to call concurrently from many threads.
fn apply(&self, req: DocApiEnvelope) -> ApiResult<Receipt>;
/// Cheap host-liveness probe (shm has no socket-disconnect to detect a dead peer).
fn alive(&self) -> bool {
true
}
}