Table of Contents

Holding a Request to the Open Project

The service takes two things from the open project as each request arrives: the folder ProjectDirectory names, and the objects an edit addresses — a tool by its id, a mission command by its index path, a step color tree by its key, an indexing table by its number, a geometry or a transformer by an object-store key. A request built on one project and handled after another browser or script made, loaded, reloaded or closed one, or saved the open one into another folder, therefore acts on the project open then. Two optional preconditions keep a request to the project it was built on — ifProjectDirectory for the folder, If-Project-Generation for the project itself — and a request that states neither is served as before.

Holding a Request to the Project Folder

ProjectDirectory is resolved as each request arrives, to the folder of whatever project is open then. When another browser or script loads or makes a project in another folder, or saves the open one as a file in another folder, between a caller's read of the project and its next request, that request acts at the same relative path in the new folder. Every route that takes a rootName — the routes under /api/file-explorer but roots and those under /api/csv-strip, stl-preview/show/{renderingConnectionId}, StlFile/UpdateSource, CubeTreeFile/UpdateSource, mech/background-coolant/load and save-as, the cutter's three material loads, Workpiece/workpiece-material/load and cutting-parameter/load, mech/machine-tool/load and mech/spindle-capability/load-file — therefore takes an optional query parameter, ifProjectDirectory, whatever its verb and whether or not it has a body:

POST /api/file-explorer/write-text?ifProjectDirectory=jobs/bracket-a
{ "rootName": "ProjectDirectory", "relativePath": "NC/op10.nc", "content": "…" }
  • The value is the folder the caller takes ProjectDirectory to name: the folder of projectPath in GET /api/Project/status — that path without its last segment, . for a project file directly in the admin folder. Either separator is accepted, with a trailing one or without; otherwise the value is compared letter for letter with the spelling the status gives, on Windows too, so a Save As or a Load that only respells the folder's letters names another folder here. The status's projectDirectory is accepted as well when it is a fully qualified path, which for a project under the admin folder it is when that folder is configured as one.
  • When the folder matches, the request is served as it would be without the parameter. The folder is compared, not the project file: a Reload, a Load of another project file in the same folder and a Save As to another file in it refuse nothing here.
  • When it does not, the route answers 412 where it resolves the root, and nothing is read or written: { success: false, message, code: "ProjectDirectoryMoved", args: { ifProjectDirectory, current } }. ifProjectDirectory is the value as sent, with the roots' absolute paths written as their tokens (<Admin>, <Project>, <Resource>) when it is fully qualified; current is the folder the root names now, in the status's admin-relative, forward-slash spelling — <Project> for a project on another volume than the admin folder, which has no such spelling, and the drive alone, D:, for a project file at that volume's root. Read the status again before deciding whether the request still applies, and take the folder to send from it.
  • A check a route makes before the root answers first. A missing body, file name, or locate's line and row, a stl-preview/show whose rendering connection has no display engine, and on the routes that look one up an object-store key (or one of another type, 409), tool (or its milling cutter, for a coating load), coating layer, workpiece, equipment or coolant condition the project now open does not have, get the route's own 400, 404, 409 or success: false: nothing is done, but nothing says the folder moved. An empty relFile on StlFile/UpdateSource or CubeTreeFile/UpdateSource clears the reference before the root is looked at. The routes outside /api/file-explorer, /api/csv-strip and stl-preview are held to the project generation as well, which a request that states it has compared before all of these but a missing or malformed body, a 400 whatever the generation (below).
  • With no project open, the route answers as it does without the parameter, and under AdminDirectory or ResourceDir the parameter is not looked at.
  • Without the parameter, or with it empty, a route is served as before: the root is the folder of the project open when the request arrives — on a route held to the project generation, only while that is still the generation the request states, when it states one.

The browser client sends the parameter with every such request under ProjectDirectory once it knows the project's path. On a 412 that its response helper reads (every one but a download opened in a new tab and an image a Markdown file draws, which the browser reads itself) it fetches GET /api/Project/status at once and rebuilds its screens. Not held to the folder: the three routes that take a project-relative path with no root name (POST /api/NcProgram/file-lines, POST /api/Mission/ncfile-info, POST /api/Mission/preview-ncfile) read under whatever folder the open project has when they arrive, and the routes that take an absolute folder (baseDirectory) instead of a root name — ObjectManagement/Load, SaveAs, Copy, Paste, GetXml and ApplyXml, StlFile/NewWithPath, UpdateSourceFile, GetFileInfo and Reload, mech/machine-tool/update, mech/spindle-capability/load and update — act in the folder they are given. All of them but NcProgram/file-lines take the project generation (below).

Holding a Request to the Project Generation

Every route below takes an optional request header, If-Project-Generation, whatever its verb and whether or not it has a body:

PUT /api/Workpiece/init-resolution
If-Project-Generation: 1763712345678
Content-Type: application/json

0.25
  • The value is projectGeneration as GET /api/Project/status gives it — the execution status and the answers of a project New, Load, Save As, Reload and Close carry the same value — written as a decimal whole number. New, Load, Reload and Close move it, and so does one of them that let the open project go or replaced it and then failed. A Save As does not, since the project in memory stays the same, so it refuses nothing here; the folder it moves is ifProjectDirectory's. A service counts from the moment it started, so after a restart a request built before it is refused too.
  • When it matches, the request is served as it would be without the header.
  • When it does not, the route answers 412 and does nothing: { success: false, message, code: "ProjectGenerationMoved", args: { ifProjectGeneration, current } }, ifProjectGeneration the value as sent and current the service's generation now. The comparison comes after the request's body is read and checked — a malformed body is a 400 whatever the generation — and before everything else the route checks: a request naming a key, a tool or a workpiece the project now open does not have is answered 412, not 404, and during a run 412, not the run's 409. On a route that takes ifProjectDirectory too, the generation is compared first: after a New, Load, Reload or Close the answer is ProjectGenerationMoved, after a Save As into another folder ProjectDirectoryMoved.
  • While a project change runs, a request that arrives waits for its end and is answered then: 412 when the change moved the generation, served when it did not (a change refused as busy, say). A change still running after 20 s leaves the request answered 503 with Retry-After: 1 and a plain-English message, no code, nothing done: send it again. A client that leaves during the wait is answered 499.
  • A malformed header — anything but a decimal whole number, a sign or a second value included — answers 400, nothing done. Blanks around the number are let go, and a blank header counts as none.
  • Without the header, a request is served as before, on whichever project is open when it is handled. GET, HEAD and OPTIONS are never compared, and the routes not listed below ignore the header.

Held, or compared on arrival. Most of the routes hold a request to its generation through the action: from the comparison to the action's end no New, Load, Reload or Close begins, so a request is never compared against one project and applied to the next. A change asked meanwhile waits for the held requests; when one is still running 10 s on, the change is refused with 409 and nothing changed (The project cannot be changed while a request that stated the project generation is still applying its edit …), and it can be asked again. An ordinary edit takes milliseconds; one that reads a large file into the project — an STL, a stock file, a machine tool — holds a change off for the whole read. The reads that are POSTs, the routes that only make or replace an object-store entry and the build of the stock are compared as they arrive — the 412, the wait and the 503 alike — and then run without holding a change off: step-color-trees/check and preview, step-variables/compile-check and preview, Mission/commands/{path}/compile-check, Mission/compile-check, Mission/ncfile-info, Mission/preview-ncfile, StlFile/NewWithPath and GetFileInfo, mech/machine-tool/xml, StaticFreeform/InvertMat, Workpiece/meshed-geom/build, and every non-GET route of /api/ObjectManagement. Of these, ObjectManagement/Load, LoadResource, Paste and ApplyXml and StlFile/NewWithPath write one object-store entry once their object is made: that write is compared again and made inside the hold, so a project replaced meanwhile refuses it the same way. A change asked while one of them runs begins at once, with one exception that comes from the stock, not from the hold: a change takes the stock down, and a build of it under way is cancelled when it is a voxelization, while a meshed-geometry file being read is waited out inside the change, so the change lasts as long as the read and a request that states a generation waits with it, 503 after 20 s.

Which routes. The header is taken by every non-GET route of /api/execution/step-color-trees, /api/execution/step-variables, /api/Mission, /api/Controller, /api/mech/soft-nc-runner, cl-runner, csv-runner, machine-tool, spindle-capability, background-coolant and equipment-topology, /api/ToolHouse, /api/Cutter, /api/CylindroidHolder, /api/FreeformHolder, /api/Workpiece, /api/Fixture, /api/ObjectManagement and the generic geometry and transformer editors (/api/Box3d, CubeTreeFile, Cylindroid, ExtendedCylinder, GeomCombination, StlFile, TransformationGeom, DynamicRotation, DynamicTranslation, GeneralTransform, NoTransform, StaticFreeform, StaticRotation, StaticTranslation) — the index-only POSTs a page sends as it is set up (Initialize, Index…) among them — and the charts' POST /api/execution/inspecting-key, strip-chart-item-config and color-guide, all held but the routes compared on arrival above. Every other route ignores the header: the project-file routes under /api/Project — a Save, Save As, Reload or Close from a caller that has not caught up still acts on the project open now —, the run controls under /api/Execution (start, pause, resume, stop, reset, run-line, run-step), the display and selection routes (/api/execution/cl-strip, mech/tool-house-display, mech/equipment-setup-display, rendering-flags, stl-preview), /api/file-explorer and /api/csv-strip, /api/NcProgram, and the engine's own /api/SessionShell, /api/LocalProjectService and /api/Setup, some of which write the project. The Swagger document lists the optional header on every operation that takes it, held or compared on arrival, with the 412 and the 503 among its answers.

What a script does. Read GET /api/Project/status before the first edit and send its projectGeneration with every edit. On a 412 ProjectGenerationMoved, send nothing more on the old basis: read the status again and decide whether the work still applies to the project now open. If it does, rebuild what was built on the old one — the object store empties at every project change, so every key indexed before is gone, and the ids, paths and numbers read before name the new project's objects — and state the new generation (args.current, or the status's) from then on. On a 503, wait as Retry-After says and send the same request again; on a 409 from a New, Load, Reload or Close that names an edit still being applied, ask again once that edit has had time to finish.

The browser client states the generation it holds on every non-GET request under /api/ once it has read one, and on a ProjectGenerationMoved reads the status at once and rebuilds its screens on the project now open (Session State). It states the generation it holds when the request is sent, so a request a screen sends only after the browser took the newer one is served; the senders that wait before they send — the mission's script autosave, the strip charts' range and color boxes, the equipment topology's queued edits — check for a replaced project themselves and send nothing.

See Also

  • Driving the Web Service over HTTP — the contract, the reply envelope, the named roots and the project lifecycle these preconditions sit on
  • One Service, One Project — what else to check before driving an instance others use, and what is refused while a run is live or the project is changing
  • File Explorer Refusals — the File Explorer's own codes beside ProjectDirectoryMoved, and how the browser shows them