Table of Contents

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/status and GET /api/Execution/status. Do not take over while another person's project is open or a run is Running or Paused; a dedicated instance is the safe choice for a scripted build.
  • Send ifProjectDirectory with each request that names a file under ProjectDirectory (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-Generation with each edit (Holding a Request to the Project Generation): once someone else has made, loaded, reloaded or closed a project, the edit is answered 412 ProjectGenerationMoved and 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 runId that POST /api/Execution/start returns and the instanceId beside it — the service process the runId counts 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 (Running or Paused) every non-GET route of /api/ToolHouse, /api/Cutter, /api/CylindroidHolder and /api/FreeformHolder answers 409 { 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' Get and IndexCurrentGeometry); 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/PlayNcFile and its siblings, which executionStatus does not show), the generic object-store routes (/api/Box3d, /api/Cylindroid, /api/StlFile, /api/TransformationGeom, /api/StaticTranslation, …) answer 409 { 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 as TransformationGeom/IndexGeom, pass; TransformationGeom/IndexTransformer on a wrapper there that has no transformer yet is refused, since it would write a NoTransform on the null field), and the six solid routes of /api/mech/equipment-topology — enable-geom, disable-geom, create-geom, set-geom-transform, refresh-geom-cache and POST …/rgb — answer the same, as does its index-geom on 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 (Running or Paused), POST /api/SessionShell/PlayToolingTeleport and PlayClTeleport play nothing, and OptimizeToFiles and ConvertClToNcFiles write nothing: each answers 409 with success: false and one entry in messages whose id names the reason — Play--BusyAct, OptimizeToFiles--Busy, ConvertClToNc--Busy — and the same message is in the shell list of GET /api/Execution/messages. A teleport is refused the same way with Play--BusyActAnotherThread while another request plays an NC program on the session, with Play--Reviewing while a play result is under review or another request is opening one, and with Play--BusyActReview while 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--Busy while the player is locked, Play--BusyAnotherThread while another request plays, Play--BusyReset while the player is being reset, Play--BusyReview in 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, Diff and RemoveFlyPiece — and the aliases ExportRuntimeGeomToStl, WriteRuntimeGeom and ReadRuntimeGeom — 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/status reads Running meanwhile, POST /api/Execution/start and run-step answer 409 { success: false, code: "Start--BusyOneShot", message } and run-line answers RunLine--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, a Diff — answers before that work runs. Then a start is refused until the other work has ended. The answer is 200, or 409 with success: false and one entry in messages (also in the shell list) whose id names the reason, nothing written or changed — MeshedGeomCall--BusyAnotherThread while another request plays an NC program or a teleport on the session; MeshedGeomCall--BusyReset while the session is torn down by a Reset, a project change, ResetRuntime or EndSession; MeshedGeomCall--NoSession when the session ended or was replaced between the request and the player thread; MeshedGeomCall--BusyReview while another request opens or closes a play result review (POST /api/LocalProjectService/OpenNcResultReview or CloseNcResultReview), which resets the workpiece — and an open then loads the recorded one; MeshedGeomCall--BusyPacePointTimeout when the running play reached no pace point within 30 s, and MeshedGeomCall--Busy or MeshedGeomCall--BusyBehindRecompute when another workpiece call or a step-physics recompute held the player that long; MeshedGeomCall--Canceled when 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, where RecomputeStepPhysics answers a Stop with 200 and success: false; MeshedGeomCall--TreeDiscarded when the workpiece was replaced while the call waited; MeshedGeomCall--NoGeom when ExportMeshedGeomToStl, WriteMeshedGeom or RemoveFlyPiece finds no workpiece geometry; MeshedGeomCall--BusyRunEnding as a run ends, so call again a moment later. WriteMeshedGeom to 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>.writing beside it removed (unless, on Windows, a program holds it open without letting it be deleted); so does a <file>.writing an 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 parameter balanceNeighbourLevels (default false): POST /api/SessionShell/ExportMeshedGeomToStl?relFile=Output/part.stl&resolution_mm=0&balanceNeighbourLevels=true writes 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/ResetRuntime or EndSession is resetting the runtime or ending the session, the plays answer 409 Play--BusyReset and the teleports Play--BusyActReset, BeginSession, ResetRuntime, EndSession and Reset answer BeginSession--BusyReset, ResetRuntime--BusyReset, EndSession--BusyReset and Reset--BusyReset, and POST /api/Execution/start, run-line and run-step answer 409 { success: false, code: "Start--BusyReset", message }, as POST /api/Execution/reset answers Reset--BusyReset. While another request plays a teleport, ResetRuntime, EndSession and the two resets answer ResetRuntime--BusyAct, EndSession--BusyAct and Reset--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/OpenNcResultReview or CloseNcResultReview), POST /api/Execution/start and run-step answer 409 { success: false, code: "Start--BusyReview", message } and run-line answers RunLine--BusyReview; a reset, ResetRuntime or a project change asked meanwhile waits for the open or close to finish, then runs. The open and the close themselves answer 409 with NcResult-Review--BusyReset while a project change, a ResetRuntime, an EndSession or a reset runs, and with NcResult-Review--BusyAct while another request plays a teleport.

See Also