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

+66
View File
@@ -0,0 +1,66 @@
//! `ocs_doc_api` — Object-oriented, transport-agnostic CAD entity API for
//! OpenCADStudio plugins and hosts (v2).
//!
//! Core vocabulary: **Entity**, **ObjectId** (u64), **Operation** (typed write),
//! **Query** (typed read), **Transport** (the only plugin↔host boundary).
//! Every write op is one atomic host call = one undo step (no multi-op write
//! transactions — removed after the security/integrity review; see the plan §13).
//!
//! The facade is object-centric: [`DocApi`] (root) → [`Document`] → collections
//! ([`SolidCollection`], [`CurveCollection`], [`EntityCollection`]) → typed
//! handles ([`Solid`], [`Line`], …) carrying geometric methods. The same typed
//! requests run in-process and over IPC; only the [`Transport`] differs.
pub mod error;
pub mod id;
pub mod revision;
#[cfg(feature = "host")]
pub mod backend;
#[cfg(feature = "host")]
pub mod executor;
#[cfg(feature = "host")]
pub mod geom;
pub mod envelope;
pub mod facade;
pub mod ops;
pub mod query;
pub mod transport;
// Generated (build.rs) — committed snapshots under src/gen/; do NOT edit by hand.
pub mod gen {
pub mod ops {
include!("gen/ops_gen.rs");
}
pub mod query {
include!("gen/query_gen.rs");
}
pub use ops::Operation;
pub use query::Query;
}
pub use error::{ApiError, ApiResult, GeometryErrorKind};
pub use id::ObjectId;
pub use revision::GeometryRevision;
pub use envelope::{DocApiEnvelope, EnvelopeBody, OpOutcome, Receipt};
pub use facade::{
CurveCollection, DocApi, Document, Entity, EntityCollection, HasId, Line, OpGroup, Point,
Polyline, QueryBatch, QueryResults, Solid, SolidCollection,
};
pub use ops::{BoolOp, Curve2Spec, EntitySpec, Operation, PlacementSpec, SolidPrimitive};
pub use query::{Aabb, EntityView, Query, QueryResult};
pub use transport::Transport;
/// The crate's own wire-envelope protocol version (`DocApiEnvelope::version`).
/// Bump when the envelope layout or `Operation`/`Query` discriminants change.
/// Bridges must check this before speaking (see `bindings/README.md`).
pub const ENVELOPE_VERSION: u16 = 1;
/// The generated binding handover schema (plan §10.2): object model + method
/// signatures + op/query mapping with traced wire layouts inlined. Single,
/// self-contained, versioned with [`ENVELOPE_VERSION`].
pub fn binding_schema_json() -> &'static str {
include_str!("gen/binding_schema.json")
}