File Explorer Refusals
A refusal a user meets in normal use carries a stable code and its args beside the English message. The bodies are built in Common/FileRefusals.cs and sent by the three controllers behind this page: Common/FileExplorerController.cs, Common/CsvStripController.cs (its sidecar routes included) and the STL preview's show in Disp/StlPreviewController.cs. One code is not the page's own: ProjectDirectoryMoved, built in Common/ApiError.cs and sent by every route that addresses a file by named root, in ten controllers — these three and the seven listed below the table.
| Code | Status | args |
Refused |
|---|---|---|---|
FileExplorerRootUnavailable |
400 | root — the root's name as sent |
a named root that is not there: ProjectDirectory while no project is open, or a name the server does not know |
FileExplorerPathNotFound |
404 from list, download-zip, rename and copy (the source), delete and the STL preview's show; 400 from the routes that need an existing file — read-text, read-lines, write-lines, download, extract-zip — and from the CSV strip routes |
path — the root-relative path as sent |
a folder or file that is not there: moved or deleted since it was listed |
FileExplorerPathTaken |
400 | path — the path that is taken; for extract-zip, the folder's name |
create-file over a file or a folder, create-directory over a file, a rename onto an existing name, an extract-zip beside a folder of the archive's name |
FileExplorerPathOutsideRoot |
400 | none | a path that leaves its root: .. past the top, or, on Windows, an absolute path on another drive (Z:/x under a root on C:); a path that names a git directory or anything in one, every path under a root that lies in one, and an extract-zip whose folder would be one, such as that of .git.zip (File Explorer Page) |
FileExplorerCopyNamesTaken |
400 | none | a copy that finds -Copy-00 through -Copy-19 all taken |
FileExplorerFileIsLink |
400 from write-lines |
none | the CSV strip viewer's Save of a file that is a link (a reparse point, such as a symbolic link): the rewrite would put a plain file where the link was, and the link's target may lie outside the root |
FileExplorerFileReadOnly |
400 from write-lines and write-text |
none | a file with the read-only attribute: the CSV strip viewer's Save and the text editor's; a write-text to a path with no file yet is no refusal |
FileExplorerLineNotUtf8 |
400 from write-lines |
line — the line's 1-based number in the file on disk |
a line the Save replaces whose bytes are not UTF-8 — a CSV Excel saved in Big5, say; a line the Save deletes, or inserts rows after, is not checked |
FileExplorerAccessDenied |
400 from write-lines and write-text |
none | the operating system denies the server's process writing the file (its permissions, a security setting): for write-lines when the file is opened for an in-place write, when the rewritten copy is created beside it (a folder that lets the file be written but no file be created) or when that copy replaces it; for write-text when the file is written. Not retried; nothing was written |
FileExplorerFileInUse |
400 from write-lines and write-text |
none | another program (Excel, say) holds the file open without sharing it: for write-lines through every retry of the in-place open or of the replace, about three seconds; for write-text at once, on Windows' sharing or lock violation, with no retry. Nothing was written |
FileExplorerInvalidName |
400 from create-file, create-directory, rename (the destination) and upload |
name — the first name in the path that has such a character, as sent, scrubbed; chars — those characters in the order they first appear, a space between, a control character written U+XXXX |
a name the server's file system cannot hold (below) |
ProjectDirectoryMoved |
412 from every route that addresses a file by named root, in all ten controllers, where it resolves the root (below) | ifProjectDirectory — the folder as the request stated it, with the roots' absolute paths as their tokens when it is fully qualified; current — the folder the Project root names now, relative to the Admin root with forward slashes: <Project> for a project on another volume than the Admin root, and the drive alone, D:, for a project file at that volume's root |
a request under ProjectDirectory whose query parameter ifProjectDirectory names another folder than the root does: another tab or client loaded or made a project of another folder, or saved the open one as a file of another folder, and the sender had not heard. Nothing is read or written. With no project open the route answers as it does without the parameter |
FileExplorerInvalidName is checked after the root and before the path is resolved: every name of the path — the separators / and \ split them — against Path.GetInvalidFileNameChars of the server, the separators aside, which on Windows is ", <, >, |, :, *, ? and the control characters, and on Linux NUL alone. So on Windows a first name such as a:b, which the resolver would take for the path A:\b on another drive, is this refusal, and no such name reaches the operating system, whose own English would answer it. On Windows the drive of an absolute path (C:\ or C:/) is no name and is skipped, so an absolute path under the root, which a client may send, is not refused for its drive's colon. No other root is skipped: the resolver trims leading separators, so \\a?b and /a?b are the name a?b under the root and are refused like it.
ProjectDirectoryMoved comes from the page's own routes — every /api/file-explorer route but /roots, the six /api/csv-strip routes and stl-preview/show — and from the seven other controllers' routes that address a file by named root: StlFile/UpdateSource, CubeTreeFile/UpdateSource, mech/background-coolant/load and save-as, the cutter's flute-material/load, shank-material/load and coating-layers/{index}/material/load, Workpiece/workpiece-material/load and cutting-parameter/load, mech/machine-tool/load and mech/spindle-capability/load-file. The SPA sends the parameter on every such request under the Project root while it holds a project path, and the routes the SPA does not call take it from a REST client. A request without it, or under another root, is served as the root resolves when it arrives. A check a route makes before it resolves the root answers first with the route's own status — 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 (StlFile, CubeTreeFile: 404, or 409 for a key of another type), a tool, its milling cutter (the coating load) or coating layer, the workpiece, the equipment or the coolant condition (save-as) of the project now open: nothing is done, but the answer carries no ProjectDirectoryMoved and the SPA does not read the status on it; an empty relFile on the two UpdateSource routes clears the reference before the root is looked at. The seven other controllers are held to the project generation as well: a request that states it — the SPA's do — and arrives after a New, Load, Reload or Close is answered 412 ProjectGenerationMoved before any of these checks but a missing body, which is a 400 whatever the generation, and before the root is resolved, and the SPA reads the status on that one. What the value is and how it is compared: Holding a Request to the Open Project.
The English message keeps each site's own sentence — Directory not found: …, A file already exists at: …, the STL preview's Path escapes the chosen root, write-lines' The file is read-only and line <n> is not UTF-8 and cannot be edited here — with its paths scrubbed; FileExplorerInvalidName's is Invalid name: <name>, and ProjectDirectoryMoved‘s names both folders as args carries them, the parameter, and that nothing was done. args.line numbers the line from 1, as a text editor and the CSV strip viewer number the file on disk, while the English <n> keeps the 0-based number write-lines takes. A refusal only a broken client meets carries no code and stays plain English: an empty root name, a missing body, a write-lines with no edits, a delete or a duplicate of the root itself, Not a .zip file, an upload with no file, a CSV locate with neither a line nor a row. So does one a user can meet: an extract-zip whose archive holds an entry named .git or in a git directory, The archive holds a git directory (.git) and was not extracted; zip the folder again without it, which the banner shows in English in every language. So do the rest of write-lines’ 400s: a malformed change — an entry or its text missing, an insert of no lines, a line replaced, deleted or inserted after twice or both replaced and deleted, a line number below 0 or past the last line, a text with a line break in it or with a trailing carriage return its line break would not keep, a first line that would start with U+FEFF in a file without a byte-order mark, an expectedLength below 0 — and a line on disk or a new text over 16 KiB, both of which the CSV strip viewer refuses before it sends. So does the runtime's own exception text, scrubbed — an upload over a read-only file or one another program holds, a rename or delete of a file or folder another program holds: the operating system's sentence answers them. The two Saves are the exception, since a CSV can be saved from either the strip viewer (write-lines) or the text editor (write-text): both answer FileExplorerFileReadOnly, FileExplorerAccessDenied and FileExplorerFileInUse for the same file in the same state. create-directory over an existing folder is no refusal: it succeeds and changes nothing.
A scrubbed path changes in its prefix alone: the rest keeps the server's own separators, a / after the token on Linux and a \ on Windows. The prefixes are replaced in the order Admin, Project, Resource, and the Resource root is Admin's folder Resource, so with the shipped settings, which give Admin as an absolute path, a path under Resource reads <Admin> followed by Resource; a project usually lies under Admin as well and reads <Admin> likewise, so <Project> appears only for a project kept outside Admin, and <Resource> not at all. An Admin configured as a relative path is not found in the absolute path an exception writes: no path then reads <Admin>, and one under Resource, a root the server resolves to an absolute path, reads <Resource>.
On screen, the page's error banner — and the STL preview's and the CSV strip viewer's own — reads the code's sentence (apiErrors.fileExplorer*, and apiErrors.projectDirectoryMoved) in the app's language alone, with no HTTP <status>: before it (the status goes to the browser console), English included: the client writes these codes' English itself (EN_FROM_BUNDLE in wwwroot-src/src/api/http.ts) instead of showing the server's, which names a root by its internal name, Duplicate's names in program notation and a line by the 0-based number write-lines takes; the bundle's sentences for a read-only file, a line not in UTF-8, a denied write and a file held open also say what to do — remove the read-only setting; convert the file to UTF-8 (Notepad's Save As) or export it again, rather than save it through Excel, which keeps only the first 1,048,576 rows and writes times back in their displayed format; ask whoever manages the computer running HiNC, since it is HiNC's process that is denied; close the file in the other program. args.root is shown by the root's on-screen title (explorer.roots.*, through wwwroot-src/src/api/namedRoots.ts), never as ProjectDirectory. The CSV strip viewer's banner numbers the line of a FileExplorerLineNotUtf8 as the gutter of its text half does: the refused changes stay pending, and the gutter numbers the lines as they will be after Save, so rows the same Save inserts or deletes above the line move its number away from args.line (writeRefusalText in CsvStripPane.vue, through HttpError.reworded, which renders a coded error again with an argument replaced).
ProjectDirectoryMoved reads The project changed: nothing was done. in the notice of whichever screen sent the refused request — its server English names the parameter and both folders, which is for a REST client — and the response helper that reads it also has the project store read GET /api/Project/status at once, one read at a time, so the pages are rebuilt on the project now open without waiting for the status hub. The CSV strip viewer's Save counts the 412 as refused, nothing written, as it counts a 400 or a 409, and the paged viewer says it and stops polling, as on a 400. Where the browser reads the answer itself, it gets the 412 body: a download opened in a new tab shows its JSON there, and an image a Markdown file draws from the Project root through /download is not drawn. How coded errors render in general: The Server Half.
Source Code Path
Common/FileRefusals.cs— the coded bodies, every message and path argument scrubbedCommon/FileExplorerController.cs,Common/CsvStripController.cs,Disp/StlPreviewController.cs— the routes that send them;TryCheckNamesin the first, the names checked before a path is resolvedCommon/TextLinePatch.cs—LinePatchRefusal, which of the line patch's refusals a user meets;FileRefusals.ForLinePatchanswers those with a code and the rest plainCommon/NamedRootResolver.cs— the root names andScrubAbsolutePaths, which replaces the prefixes Admin first;IsUnderRootwithNamesGitDirectory, which reads a path into a git directory as one outside the root; theTryResolveRootthat takesifProjectDirectory, compares it withProjectFolderForClientsand hands backProjectRootMoved, the 412 every by-root route answers withCommon/ApiError.cs—ProjectDirectoryMoved, its body and EnglishGeom/StlFileController.cs,Geom/CubeTreeFileController.cs,Mech/BackgroundCoolantController.cs,Mech/CutterController.cs,Mech/WorkpieceController.cs,Mech/MachineToolController.cs,Mech/SpindleCapabilityController.cs— the seven other controllers whose by-root routes answerProjectDirectoryMovedwwwroot-src/src/api/http.ts—API_ERROR_KEYS,EN_FROM_BUNDLE,labelledArgs;HttpError, which keeps a coded body'scodeandargs, and itsreworded;onProjectDirectoryMoved, the hook the project store's status read hangs onwwwroot-src/src/api/fileExplorer.ts—projectRootQuery, theifProjectDirectoryevery by-root call of thesrc/apimodules adds under the Project rootwwwroot-src/src/stores/project.ts— the status read aProjectDirectoryMovedstarts, one at a timewwwroot-src/src/components/CsvStripPane.vue—writeRefusalText, the banner of a refused Save with the line numbered as the gutter numbers itwwwroot-src/src/api/namedRoots.ts— a root's name onto its on-screen titlewwwroot-src/src/i18n/en/apiErrors.ts— thefileExplorer*sentences andprojectDirectoryMoved(and the other four languages' files of the same name)scripts/lint-api-error-codes.mjs— failsnpm run buildon a server code the client does not map.ai/project-root-precondition-e2e.mjs— the acceptance ofProjectDirectoryMoved: over the API, every by-root route's 412, code andargswith nothing changed on disk — butstl-preview/show, which answers 404 there for want of a rendering connection and whose 412 the browser's STL preview row reaches — the right folder and no folder answered as before, the parameter changing nothing with no project open; in the browser, a tab that has not heard of another client's Save As or Load refused on its Auto Save, upload, rename, delete and CSV strip Save, nothing written, and its pages rebuilt before the status hub says anything; a File Explorer set up before the first status.ai/file-explorer-refusals-i18n-e2e.mjs— the acceptance of the page's own codes: every route's status, code,args, English and scrub; the banner in five languages; and, in its section F, the second batch: over the API, a read-only CSV, a line in Big5, a CSV another program holds open, one under an ACL denying writes and a folder that denies creating the temp file, saved throughwrite-linesandwrite-text; names with?,*,<,>,|,",:, a Tab and leading separators; a path on a drive the host does not have; in the browser, in Traditional Chinese and in English, the banner of a new folder nameda?band of the strip viewer's Save of a read-only CSV, of a Big5 line with a row inserted above it (the line as the gutter numbers it) and of a CSV held open
See Also
- File Explorer Page — the page whose routes these are
- File Explorer Source Code — the route tables and the controllers that send these refusals
- STL Preview Pane — its
showrefusals and the preview's own banner - Internationalization: the Server Half and the Build Gate — how coded errors render, and the lint that holds the server's codes to the client's table
- Driving the Web Service over HTTP — a script reads these refusals by
code, not by their English - Holding a Request to the Open Project —
ifProjectDirectoryand the project generation, which a request states so that it does nothing once the project moved