One Service, One Project
A service instance holds exactly one open project and one object store, shared by every browser and
every script connected to it. Signing in decides who may connect, not whose project it is.
POST /api/Project/new or POST /api/Project/load replaces the project everyone on that instance is
working on, and the run controls act on whatever run is current: POST /api/Execution/stop takes no
run identifier and stops the run in progress, whoever started it. A request reaches whichever project
is open when the service handles it, unless it states the project folder or the project generation it
was built on, on the routes that take them
(Holding a Request to the Open Project): then it is
refused, and does nothing, once another caller has moved the folder or replaced the project.
Before driving an instance other people may be using:
- Read
GET /api/Project/statusandGET /api/Execution/status. Do not take over while another person's project is open or a run isRunningorPaused; a dedicated instance is the safe choice for a scripted build. - Send
ifProjectDirectorywith each request that names a file underProjectDirectory(Holding a Request to the Project Folder): once someone else has loaded or made a project in another folder, or saved the open one into another folder, the request is refused and does nothing, instead of acting at the same path there. - Send
If-Project-Generationwith each edit (Holding a Request to the Project Generation): once someone else has made, loaded, reloaded or closed a project, the edit is answered 412ProjectGenerationMovedand does nothing, instead of acting on the object of the same id, path or key in the project open then. The project-file routes and the run controls take no such header: a Save, Reload, Close or Start acts on the project open when it arrives. - Give every object-store key a prefix no other caller uses (see Editing Objects by Key).
- Identify a run by the
runIdthatPOST /api/Execution/startreturns and theinstanceIdbeside it — the service process therunIdcounts in — and never stop a run from a timeout (see Running a Replay). - Do not edit the tool house, or the machine tool's and the fixture's solids, while a run is live.
While the player is locked (
RunningorPaused) every non-GET route of/api/ToolHouse,/api/Cutter,/api/CylindroidHolderand/api/FreeformHolderanswers409 { success: false, code: "ToolEditRefusedWhileRunning" }and changes nothing, except the index-only POSTs the tool-house page issues on every open (Initialize,SelectTool,{id}/inner-beam,{id}/upper-beam, the holders'GetandIndexCurrentGeometry); stop or reset first. While it is locked, and while a play a host request drives directly on the session shell is in flight (POST /api/SessionShell/PlayNcFileand its siblings, whichexecutionStatusdoes not show), the generic object-store routes (/api/Box3d,/api/Cylindroid,/api/StlFile,/api/TransformationGeom,/api/StaticTranslation, …) answer409 { success: false, code: "SolidEditRefusedWhileRunning" }to a write whose key names an object under the machine tool's or the fixture's solids, which the runtime copy shares with the setup instead of copying them (their index-only POSTs, such asTransformationGeom/IndexGeom, pass;TransformationGeom/IndexTransformeron a wrapper there that has no transformer yet is refused, since it would write aNoTransformon the null field), and the six solid routes of/api/mech/equipment-topology—enable-geom,disable-geom,create-geom,set-geom-transform,refresh-geom-cacheandPOST …/rgb— answer the same, as does itsindex-geomon an anchor that has no solid yet, since it would hang one. For a tool the generic routes are not gated by the player: a script must not send them against a tool's keys during a run either — the cutter they edit is the one the run cuts with, and only the resync that follows would be refused. - Do not teleport, optimize or convert over HTTP while a run is live. While the player is locked
(
RunningorPaused),POST /api/SessionShell/PlayToolingTeleportandPlayClTeleportplay nothing, andOptimizeToFilesandConvertClToNcFileswrite nothing: each answers 409 withsuccess: falseand one entry inmessageswhoseidnames the reason —Play--BusyAct,OptimizeToFiles--Busy,ConvertClToNc--Busy— and the same message is in theshelllist ofGET /api/Execution/messages. A teleport is refused the same way withPlay--BusyActAnotherThreadwhile another request plays an NC program on the session, withPlay--Reviewingwhile a play result is under review or another request is opening one, and withPlay--BusyActReviewwhile another request opens or closes a review at a moment no review stands — mostly while a close is clearing it. The program plays (PlayNcFile,PlayNc, …) answer 409 the same way:Play--Busywhile the player is locked,Play--BusyAnotherThreadwhile another request plays,Play--BusyResetwhile the player is being reset,Play--BusyReviewin that same moment of another request's review open or close. Make these calls after the run. - Expect a workpiece call to hold the play.
POST /api/SessionShell/ExportMeshedGeomToStl,WriteMeshedGeom,ReadMeshedGeom,DiffandRemoveFlyPiece— and the aliasesExportRuntimeGeomToStl,WriteRuntimeGeomandReadRuntimeGeom— first wait for the cutting already queued to finish, and the play stands still while they run, so a file they write holds every step played before the request and no step cut halfway. During a run the call is taken at the play's next pace point; a paused run takes it where it is parked and stays paused. With the player idle the call runs as a job of its own:GET /api/Execution/statusreadsRunningmeanwhile,POST /api/Execution/startandrun-stepanswer409 { success: false, code: "Start--BusyOneShot", message }andrun-lineanswersRunLine--BusyOneShot, so wait for the call's response before starting or stepping. The response then comes once the player is free again, so a start right after it is not refused — except in two cases, where it comes as soon as the call is done and the player is still held: a call made while a step-physics recompute runs on an idle player is done between two of the recompute's chunks (a paused recompute too, which stays paused), and the recompute goes on after it; and a call whose job another request queued work on meanwhile — a recompute, aDiff— answers before that work runs. Then a start is refused until the other work has ended. The answer is 200, or 409 withsuccess: falseand one entry inmessages(also in theshelllist) whoseidnames the reason, nothing written or changed —MeshedGeomCall--BusyAnotherThreadwhile another request plays an NC program or a teleport on the session;MeshedGeomCall--BusyResetwhile the session is torn down by a Reset, a project change,ResetRuntimeorEndSession;MeshedGeomCall--NoSessionwhen the session ended or was replaced between the request and the player thread;MeshedGeomCall--BusyReviewwhile another request opens or closes a play result review (POST /api/LocalProjectService/OpenNcResultRevieworCloseNcResultReview), which resets the workpiece — and an open then loads the recorded one;MeshedGeomCall--BusyPacePointTimeoutwhen the running play reached no pace point within 30 s, andMeshedGeomCall--BusyorMeshedGeomCall--BusyBehindRecomputewhen another workpiece call or a step-physics recompute held the player that long;MeshedGeomCall--Canceledwhen the player's run or job ended before the call began — stopped, reset or faulted — or a Stop came while the call waited for the steps queued ahead of it: a 409, whereRecomputeStepPhysicsanswers a Stop with 200 andsuccess: false;MeshedGeomCall--TreeDiscardedwhen the workpiece was replaced while the call waited;MeshedGeomCall--NoGeomwhenExportMeshedGeomToStl,WriteMeshedGeomorRemoveFlyPiecefinds no workpiece geometry;MeshedGeomCall--BusyRunEndingas a run ends, so call again a moment later.WriteMeshedGeomto a file that cannot be written — in a folder that cannot be written to, or on Windows a file that is read-only or open in a program that does not let it be deleted — fails with HTTP 500, the file as it was and this write's<file>.writingbeside it removed (unless, on Windows, a program holds it open without letting it be deleted); so does a<file>.writingan earlier write left beside the file that cannot be removed, which stays: make the folder writable, or on Windows clear its read-only attribute, delete it or close the program that holds it, and call again. A written file replaces the old one, it is not written into it: the folder must be writable even where the file itself is, and on Linux a read-only file or a symbolic link of that name is replaced too. On Windows a file that other programs have open is replaced as well when each of them lets it be deleted while it is open: they keep reading, and writing, the old file until they close it, and what they write meanwhile does not reach the new one (checked on Windows 11 on a local NTFS drive, and through a share of the same machine with the holder opening the file through the share, where an open file is refused; other Windows versions, other file systems, mapped drives and other machines' shares were not checked). A download of a single file from the File Explorer holds the file that way. Make these calls between plays, or pause first. The export, under either name, also takes an optional query parameterbalanceNeighbourLevels(defaultfalse):POST /api/SessionShell/ExportMeshedGeomToStl?relFile=Output/part.stl&resolution_mm=0&balanceNeighbourLevels=truewrites the even mesh of Keeping the workpiece between runs — triangle sizes that change gradually, somewhat more triangles, the workpiece unchanged. - Do not call the session or the player while the project is being changed or the runtime reset.
While a project New, Load, Reload or Close runs, or another request's
POST /api/SessionShell/ResetRuntimeorEndSessionis resetting the runtime or ending the session, the plays answer 409Play--BusyResetand the teleportsPlay--BusyActReset,BeginSession,ResetRuntime,EndSessionandResetanswerBeginSession--BusyReset,ResetRuntime--BusyReset,EndSession--BusyResetandReset--BusyReset, andPOST /api/Execution/start,run-lineandrun-stepanswer409 { success: false, code: "Start--BusyReset", message }, asPOST /api/Execution/resetanswersReset--BusyReset. While another request plays a teleport,ResetRuntime,EndSessionand the two resets answerResetRuntime--BusyAct,EndSession--BusyActandReset--BusyAct, and a project New, Load, Reload or Close answers 409 with a message naming the play, the act or the reset it waits for. Wait for it to end, then call again. A New, Load, Reload or Close also waits for the requests held to the project generation that are running, and answers 409 when one is still running 10 s on — an edit reading a large file into the project, an STL or a machine tool, can. While another request opens or closes a play result review (POST /api/LocalProjectService/OpenNcResultRevieworCloseNcResultReview),POST /api/Execution/startandrun-stepanswer409 { success: false, code: "Start--BusyReview", message }andrun-lineanswersRunLine--BusyReview; a reset,ResetRuntimeor a project change asked meanwhile waits for the open or close to finish, then runs. The open and the close themselves answer 409 withNcResult-Review--BusyResetwhile a project change, aResetRuntime, anEndSessionor a reset runs, and withNcResult-Review--BusyActwhile another request plays a teleport.
See Also
- Driving the Web Service over HTTP — the REST contract, sign-in, the reply envelope, named file roots and the project lifecycle these rules apply to
- Editing Objects by Key — object-store keys, and the prefix that keeps one caller's apart from another's
- Running a Replay — reset, start and poll on a shared instance, and what a timeout must not stop
- Holding a Request to the Open Project — the folder and the generation a request states, so that it does nothing once someone else has changed the project