SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
//! Native camera queue preparation. Runtime command metadata is distinct from
//! funded renderer storage: the long-lived shared request is an exact Vec arena.
use super::{
Kind,
batch_payload::{self, Payload},
};
use crate::{EngineError, Result, Session};
use serde_json::{Value, json};
use solidcraft_io::vfs::PathScope;
use solidcraft_render::{
Camera,
job::{CancelToken, Phase, RetainedMetadata},
};
use std::mem::size_of;
fn bad(message: &str) -> EngineError {
EngineError::Other(message.into())
}
fn check(cancel: &CancelToken) -> Result<()> {
cancel.check().map_err(crate::render_jobs::job_error)
}
#[derive(Clone, Copy, PartialEq, Eq)]
pub(crate) struct Ticket {
uid: u64,
owner: u64,
epoch: u64,
}
impl Ticket {
pub(crate) fn matches(self, s: &Session) -> bool {
self.uid == s.uid && self.owner == s.render_jobs.owner_key()
}
}
pub(crate) struct NativeState {
pub ticket: Ticket,
pub next: usize,
pub total: usize,
pub claimed: bool,
pub cancel: CancelToken,
}
struct Row {
name: String,
camera: Camera,
}
/// Opaque persistent shared request. Backing precedes its independent lease.
pub struct Plan {
ticket: Ticket,
payload: Payload,
rows: Vec<Row>,
scope: Option<PathScope>,
next: usize,
lease: RetainedMetadata,
}
impl Plan {
pub fn owner_matches(&self, s: &Session) -> bool {
self.ticket.matches(s)
}
pub fn retained_bytes(&self) -> u64 {
self.lease.bytes()
}
}
/// One exact source/front claim; a failed channel delivery retains this owner.
pub struct Claim {
ticket: Ticket,
front: usize,
first: bool,
total: usize,
source: Session,
params: Option<Value>,
scope: Option<PathScope>,
plan: Option<Plan>,
cancel: CancelToken,
}
impl Claim {
pub fn owner_matches(&self, s: &Session) -> bool {
self.ticket.matches(s)
}
pub fn is_first(&self) -> bool {
self.first
}
}
/// Success or failure owns its complete retirement path. There is no heavy Err
/// payload implicitly destroyed on the window.
pub struct Prepared {
ticket: Ticket,
front: usize,
first: bool,
total: usize,
plan: Option<Plan>,
inner: Option<super::Prepared>,
// Exact first caller input is command metadata, not persistent Plan backing.
// Keep it through current-owner policy validation and worker retirement.
first_params: Option<Value>,
error: Option<String>,
cancel: CancelToken,
committed: bool,
finished: bool,
}
impl Prepared {
pub fn owner_matches(&self, s: &Session) -> bool {
self.ticket.matches(s)
}
pub fn is_first(&self) -> bool {
self.first
}
pub fn committed(&self) -> bool {
self.committed
}
}
/// Caller starts its empty bounded worker first. Metadata refusal takes neither
/// owned input nor scope. No source capture, resource IO or job starts here.
pub fn claim(s: &mut Session, params: &mut Option<Value>, scope: &mut Option<PathScope>, cancel: CancelToken) -> Result<Claim> {
check(&cancel)?;
let input = params.as_ref().ok_or_else(|| bad("batch request was already claimed"))?;
solidcraft_io::vfs::scoped(scope.clone(), || super::validate_command_id(s, "render.batch", input))?;
s.render_batch_ready().map_err(EngineError::Other)?;
if s.model.is_stale() {
return Err(bad("finish the modelling gesture before rendering shots"));
}
let epoch = s.render_jobs.native_epoch.checked_add(1).ok_or_else(|| bad("native shot queue identity exhausted"))?;
let owner = s.render_jobs.owner_key();
if owner == 0 {
return Err(bad("render session identity exhausted"));
}
let ticket = Ticket { uid: s.uid, owner, epoch };
let total = s.doc.render.setups.len();
let source = s.scratch();
let params = params.take().ok_or_else(|| bad("batch request vanished before claim"))?;
s.render_jobs.native_epoch = epoch;
s.render_jobs.batch_error = None;
s.render_jobs.native_batch = Some(NativeState { ticket, next: 0, total, claimed: true, cancel: cancel.clone() });
Ok(Claim { ticket, front: 0, first: true, total, source, params: Some(params), scope: scope.take(), plan: None, cancel })
}
/// None means the actual current job is still running or its front is claimed.
/// Refusal preserves the plan; the consumer retires it on its worker.
pub fn claim_next(s: &mut Session, slot: &mut Option<Plan>, cancel: CancelToken) -> Result<Option<Claim>> {
check(&cancel)?;
let plan = slot.as_ref().ok_or_else(|| bad("batch plan was already claimed"))?;
if !plan.owner_matches(s) {
return Err(bad("batch plan belongs to another real session owner"));
}
// Verify the exact real owner/epoch/front before metadata errors may fail
// this queue. A stale Plan is not authority to alter a replacement ticket.
let native =
s.render_jobs.native_batch.as_ref().filter(|n| n.ticket == plan.ticket).ok_or_else(|| bad("native shot queue is no longer current"))?;
if native.claimed {
return Ok(None);
}
if native.next != plan.next || native.total != plan.rows.len() || native.next >= native.total {
return Err(bad("native shot queue front changed"));
}
let ticket = plan.ticket;
let ready = (|| {
s.advance_render_batch()?;
if !s.render_jobs.native_batch.as_ref().is_some_and(|n| n.ticket == ticket) {
return Err(bad("native shot queue is no longer current"));
}
if let Some(job) = s.render_jobs.batch_job {
let status = s.render_jobs.peek_status(job).map_err(crate::render_jobs::job_error)?;
if !status.progress.phase.terminal() {
return Ok(false);
}
if status.progress.phase != Phase::Completed {
return Err(bad("previous native shot did not complete"));
}
}
Ok(true)
})();
match ready {
Ok(true) => {}
Ok(false) => return Ok(None),
Err(error) => {
// Fixed metadata only: retain Plan/source backing for its original
// worker retirement and never touch a newer queue on this owner.
fail(s, ticket, &error.to_string());
return Err(error);
}
}
let source = s.scratch();
let front = plan.next;
let total = plan.rows.len();
let ticket = plan.ticket;
let plan = slot.take().ok_or_else(|| bad("batch plan vanished before claim"))?;
if let Some(native) = &mut s.render_jobs.native_batch {
native.claimed = true;
native.cancel = cancel.clone();
}
Ok(Some(Claim { ticket, front, first: false, total, source, params: None, scope: None, plan: Some(plan), cancel }))
}
fn shot_params(mut value: Value, camera: Camera) -> Result<Value> {
value
.get_mut("settings")
.and_then(Value::as_object_mut)
.ok_or_else(|| bad("queued render settings are missing"))?
.insert("camera".into(), json!(camera));
Ok(value)
}
fn plan_bytes(source: &Session, payload: batch_payload::Counts, scope: Option<&PathScope>) -> Result<u64> {
let rows = source.doc.render.setups.len();
let mut bytes = (size_of::<Plan>() as u64).checked_add(payload.bytes()?).ok_or_else(|| bad("batch plan byte overflow"))?;
bytes = bytes
.checked_add(rows.checked_mul(size_of::<Row>()).ok_or_else(|| bad("batch row byte overflow"))? as u64)
.ok_or_else(|| bad("batch plan byte overflow"))?;
for name in source.doc.render.setups.keys() {
bytes = bytes.checked_add(name.len() as u64).ok_or_else(|| bad("batch name byte overflow"))?;
}
bytes
.checked_add(scope.map_or(Ok(0), PathScope::retained_heap_bytes).map_err(|e| bad(&e.to_string()))?)
.ok_or_else(|| bad("batch scope byte overflow"))
}
fn first(claim: Claim, out: &mut Prepared) -> Result<()> {
out.first_params = claim.params;
let input = out.first_params.as_ref().ok_or_else(|| bad("initial batch input missing"))?;
let empty = Value::Object(Default::default());
let input = if input.is_null() { &empty } else { input };
// Both the original Batch and every nested Start retain their exact guard
// inputs for current-owner validation before the first real enqueue.
let common = crate::cmd::batch_request(&claim.source, input)?;
let (name, camera) = claim.source.doc.render.setups.iter().next().map(|(n, s)| (n.clone(), s.camera)).ok_or_else(|| bad("no saved shots"))?;
let params = shot_params(common.clone(), camera)?;
let mut inner = super::prepare(claim.source, Kind::Start, params, claim.cancel.clone())?;
inner.shot = Some(name);
out.inner = Some(inner);
let counts = batch_payload::count(&common, &claim.cancel)?;
let source = &out.inner.as_ref().ok_or_else(|| bad("missing first prepared owner"))?.source;
let bytes = plan_bytes(source, counts, claim.scope.as_ref())?;
let lease = super::submission(&out.inner.as_ref().ok_or_else(|| bad("missing first preparation"))?.capture)?
.reserve_retained_metadata(bytes)
.map_err(crate::render_jobs::job_error)?;
let mut rows = Vec::new();
rows.try_reserve_exact(claim.total).map_err(|_| bad("could not allocate batch rows"))?;
if rows.capacity() != claim.total {
return Err(bad("batch row capacity exceeds reservation"));
}
for (name, setup) in &source.doc.render.setups {
check(&claim.cancel)?;
let mut copied = String::new();
copied.try_reserve_exact(name.len()).map_err(|_| bad("could not retain batch name"))?;
if copied.capacity() != name.len() {
return Err(bad("batch name capacity exceeds reservation"));
}
copied.push_str(name);
rows.push(Row { name: copied, camera: setup.camera });
}
let payload = Payload::new(common, counts, &claim.cancel)?;
// No normalized Arc<Value> remains alongside this arena. The exact original
// Batch input belongs only to this first Prepared command metadata owner,
// never to the persistent Plan, and retires on the same worker after finish.
let plan = Plan { ticket: claim.ticket, payload, rows, scope: claim.scope, next: 0, lease };
if plan.actual_bytes()? != plan.lease.bytes() {
return Err(bad("batch arena actual backing disagrees with reservation"));
}
out.plan = Some(plan);
Ok(())
}
fn next(mut claim: Claim, out: &mut Prepared) -> Result<()> {
out.plan = claim.plan.take();
let plan = out.plan.as_ref().ok_or_else(|| bad("missing next-shot plan"))?;
let row = plan.rows.get(claim.front).ok_or_else(|| bad("batch camera row missing"))?;
let params = shot_params(plan.payload.value(&claim.cancel)?, row.camera)?;
let mut inner = super::prepare_with_metadata(claim.source, Kind::Start, params, claim.cancel.clone(), Some(&plan.lease))?;
inner.shot = Some(row.name.clone());
out.inner = Some(inner);
Ok(())
}
impl Plan {
fn actual_bytes(&self) -> Result<u64> {
let mut bytes = (size_of::<Self>() as u64).checked_add(self.payload.heap_bytes()?).ok_or_else(|| bad("batch actual byte overflow"))?;
bytes = bytes
.checked_add(self.rows.capacity().checked_mul(size_of::<Row>()).ok_or_else(|| bad("batch actual row overflow"))? as u64)
.ok_or_else(|| bad("batch actual row overflow"))?;
for row in &self.rows {
bytes = bytes.checked_add(row.name.capacity() as u64).ok_or_else(|| bad("batch actual name overflow"))?;
}
bytes
.checked_add(self.scope.as_ref().map_or(Ok(0), PathScope::retained_heap_bytes).map_err(|e| bad(&e.to_string()))?)
.ok_or_else(|| bad("batch actual scope overflow"))
}
}
/// Always returns the exact owner, including failures. Caller must retire it on
/// this same worker after finish/stale/cancel, and wait for acknowledgement.
pub fn prepare(claim: Claim) -> Prepared {
let mut out = Prepared {
ticket: claim.ticket,
front: claim.front,
first: claim.first,
total: claim.total,
plan: None,
inner: None,
first_params: None,
error: None,
cancel: claim.cancel.clone(),
committed: false,
finished: false,
};
let scope = claim.scope.clone().or_else(|| claim.plan.as_ref().and_then(|p| p.scope.clone()));
let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
solidcraft_io::vfs::scoped(scope, || {
check(&claim.cancel)?;
if claim.first { first(claim, &mut out) } else { next(claim, &mut out) }
})
}));
out.error = match result {
Ok(Ok(())) => None,
Ok(Err(error)) => Some(error.to_string()),
Err(_) => Some("native batch preparation failed internally".into()),
};
out
}
fn fail(s: &mut Session, ticket: Ticket, message: &str) {
if s.render_jobs.native_batch.as_ref().is_some_and(|n| n.ticket == ticket) {
if let Some(native) = s.render_jobs.native_batch.take() {
native.cancel.cancel();
}
s.render_jobs.batch_job = None;
s.render_jobs.batch_error = Some(message.into());
}
}
/// The real owner commits; a different current tab cannot adopt its jobs. All
/// error and successful source backing remains in `out` for worker retirement.
pub fn finish_retained(s: &mut Session, out: &mut Prepared) -> Result<Value> {
if !out.owner_matches(s) {
return Err(bad("batch completion belongs to another real session owner"));
}
if out.finished {
return Err(bad("batch preparation was already completed"));
}
let native = s
.render_jobs
.native_batch
.as_ref()
.filter(|n| n.ticket == out.ticket && n.claimed && n.next == out.front && n.total == out.total)
.ok_or_else(|| bad("native shot queue claim is no longer current"))?;
if let Err(error) = check(&native.cancel) {
out.finished = true;
fail(s, out.ticket, &error.to_string());
return Err(error);
}
let result = (|| {
check(&out.cancel)?;
if let Some(error) = &out.error {
return Err(bad(error));
}
let scope = out.plan.as_ref().and_then(|p| p.scope.clone());
let inner = out.inner.as_mut().ok_or_else(|| bad("batch preparation has no proved job"))?;
let reply = solidcraft_io::vfs::scoped(scope, || {
if out.first {
let input = out.first_params.as_ref().ok_or_else(|| bad("first batch guard input missing"))?;
let spec = crate::find_command("render.batch").ok_or_else(|| EngineError::UnknownCommand("render.batch".into()))?;
// The ordinary enablement shares this readiness predicate. Only
// this exact first claimed front is exempt from its own busy bit.
s.render_batch_ready_for_first(out.ticket).map_err(|why| EngineError::Disabled(spec.id.into(), why))?;
s.check_command(spec, input)?;
}
super::finish_inner(s, inner, Some(out.ticket))
})?;
out.committed = true;
let plan = out.plan.as_mut().ok_or_else(|| bad("batch completion has no plan"))?;
plan.next = out.front + 1;
Ok(if out.first { json!({"queued":out.total}) } else { reply })
})();
out.finished = true;
if let Err(error) = &result
&& !out.committed
{
fail(s, out.ticket, &error.to_string());
}
result
}
pub fn take_plan(out: &mut Prepared) -> Result<Option<Plan>> {
if !out.committed {
return Err(bad("batch plan cannot advance before its actual job"));
}
if out.plan.as_ref().is_some_and(|p| p.next < p.rows.len()) { Ok(out.plan.take()) } else { Ok(None) }
}
/// Metadata-only cancellation, including a first claim which has no fabricated
/// job ID. Idle/closed plans still require their separate worker retirement.
pub fn cancel(s: &mut Session) -> Result<bool> {
let Some(native) = s.render_jobs.native_batch.take() else { return Ok(false) };
native.cancel.cancel();
if let Some(job) = s.render_jobs.batch_job.take() {
// A discarded completed front can survive only in the bounded status
// history. It needs no live handle or additional cancellation; looking
// it up must not collect or evict another retained result here.
let status = s.render_jobs.peek_status(job).map_err(crate::render_jobs::job_error)?;
if !status.progress.phase.terminal() {
let _ = s.render_jobs.handle(job).map_err(crate::render_jobs::job_error)?.cancel().map_err(crate::render_jobs::job_error)?;
}
}
Ok(true)
}
/// Cleanup for a particular idle plan. Owner equality alone is deliberately
/// insufficient: an identical replacement queue has a different epoch.
pub fn cancel_plan(s: &mut Session, plan: &Plan) -> Result<bool> {
if !plan.owner_matches(s) || !s.render_jobs.native_batch.as_ref().is_some_and(|n| n.ticket == plan.ticket) {
return Ok(false);
}
cancel(s)
}
/// The native worker wraps its entire send/return/drop lifecycle here. Send the
/// release acknowledgement only after this returns, so both captured backing
/// and its temporary caller permission context have really retired. The plan
/// itself still owns/funds exactly one persistent scope between jobs.
pub fn with_scope<T>(claim: Claim, f: impl FnOnce(Claim) -> T) -> T {
let scope = claim.scope.clone().or_else(|| claim.plan.as_ref().and_then(|p| p.scope.clone()));
solidcraft_io::vfs::scoped(scope, || f(claim))
}
/// Idle, closed or rejected plan-only messages need no second stored scope.
/// Hold the lease until original scope storage and all backing have dropped.
pub fn retire_plan(plan: Plan) {
let Plan { payload, rows, scope, lease, .. } = plan;
solidcraft_io::vfs::scoped(scope, || drop((payload, rows)));
drop(lease);
}
/// Pure ordinary cancellation enablement/policy/typed-argument check. A pending
/// UI input has no invented job: None may cancel that input; Some must follow
/// the ordinary actual-job cancellation route, including ownership validation.
pub fn check_cancel(s: &Session, params: &Value) -> Result<Option<solidcraft_render::job::JobId>> {
super::validate_command_id(s, "render.cancel", params)?;
let job = crate::cmd::render_cancel_params(params)?;
if let Some(job) = job {
s.render_jobs.check_retained_or_historical_job(job).map_err(crate::render_jobs::job_error)?;
}
Ok(job)
}