diff options
Diffstat (limited to 'www/json-api/conventions.md')
| -rw-r--r-- | www/json-api/conventions.md | 649 |
1 files changed, 649 insertions, 0 deletions
diff --git a/www/json-api/conventions.md b/www/json-api/conventions.md new file mode 100644 index 0000000..f3b470c --- /dev/null +++ b/www/json-api/conventions.md @@ -0,0 +1,649 @@ +# JSON API: General Conventions +([⬑JSON API Index](index.md)) + +Jump to: + +* [JSON Property Naming](#property-names) +* [HTTP GET Requests](#http-get) +* [HTTP POST Requests](#http-post) + * [POST Request Envelope](#request-envelope) +* [Request Parameter Data Types](#request-param-types) +* [Response Envelope](#response-envelope) +* [HTTP Response Headers](#http-response-header) +* [CLI vs. HTTP Mode](#cli-vs-http) +* [Simulating POSTed data](#simulating-post-data) +* [Indentation/Formatting of JSON Output](#json-indentation) +* [JSONP](#jsonp) +* [API Result Codes](#result-codes) + +--- + +<a id="property-names"></a> +# JSON Property Naming + +Since most JSON usage conventionally happens in JavaScript +environments, this API has (without an explicit decision ever having +been made) adopted the ubiquitous JavaScript convention of +`camelCaseWithStartingLower` for naming properties in JSON objects. + +<a id="http-get"></a> +# HTTP GET Requests + +Many (if not most) requests can be made via simple GET requests, e.g. we +*could* use any of the following patterns for a hypothetical JSON-format +timeline: + +- `https://..../timeline/json` +- `/timeline?format=json` +- `/timeline?json=1` +- `/timeline.json` +- `/json/timeline?...options...` + +The API settled on the `/json/...` convention, primarily because it +simplifies dispatching and argument-handling logic compared to the +`/[.../]foo.json` approach. Using `/json/...` allows us to unify that +logic for all JSON sub-commands, for both CLI and HTTP modes. + +<a id="http-post"></a> +# HTTP Post Requests + +Certain requests, mainly things like editing checkin messages and +committing new files entirely, require POST data. This is fundamentally +very simple to do - clients post plain/unencoded JSON using a common +wrapper envelope which contains the request-specific data to submit as +well as some request-independent information (like authentication data). + +<a id="request-envelope"></a> +## POST Request Envelope + +POST requests are sent to the same URL as their GET counterpart (if any, +else their own path), and are sent as plain-text/unencoded JSON wrapped +in a common request envelope with the following properties: + +- `requestId`: Optional arbitrary JSON value, not used by fossil, but + returned as-is in responses. +- `command`: Provides a secondary mechanism for specifying which JSON + command should be run. A request path of /json/foo/bar is equivalent + to a request with path=/json and command=foo/bar. Note that subpaths + do not work this way. e.g. path=/json/foo, command=bar will not + work, but path=/json, command=foo/bar will. This option is + particularly useful when generating JSON for piping in to CLI mode, + but it also has some response-dispatching uses on the client side. +- `authToken`: Authentication token. Created by a login + request. Determines what access rights the user has, and any given + request may require specific rights. In principle this is required + by any request which needs non-guest privileges, but cookie-aware + clients do not manually need to track this (it is managed as a + cookie by the agent/browser). + - Note that when accessing fossil over a local server instance + which was started with the `--localauth` flag, the `authToken` + will be ignored and need not be sent with any requests. The user + will automatically be given full privileges, as if they were + using CLI mode. +- `payload`: Command-specific parameters. Most can optionally come in + via GET parameters, but those taking complex structures expect them + to be placed here. +- `indent`: Optionally specifies indentation for the output. 0=no + indention. 1=a single TAB character for each level of + indentation. >1 means that many spaces per level. e.g. indent=7 + means to indent 7 spaces per object/array depth level. cson also + supports other flags for fine-tuning the output spacing, and adding + them to this interface might be interesting at some + point. e.g. whether or not to add a newline to the output. CLI mode + adds extra indentation by default, whereas CGI/server modes produce + unindented output by default. +- `jsonp`: Optional String (client function name). Requests which + include this will be returned with `Content-Type + application/javascript` and will be wrapped up in a function call + using the given name. e.g. if `jsonp=foo` then the result would look like:\ +`foo( {...the response envelope...} )` + +The API allows most of those (normally all but the payload) to come in +as either GET parameters or properties of the top-level POSTed request +JSON envelope, with GET taking priority over POST. (Reminder to self: we +could potentially also use values from cookies. Fossil currently only +uses 1 cookie (the login token), and I'd prefer to keep it that way.) + +POST requests without such an envelope will be rejected, generating a +Fossil/JSON error response (as opposed to an HTTP error response). GET +requests, by definition, never have an envelope. + +POSTed client requests *must* send a Content-Type header of either +`application/json` , `application/javascript`, or `text/plain`, or the +JSON-handling code will never see the POST data. The POST handler +optimistically assumes that type `text/plain` "might be JSON", since +`application/json` is a newer convention which many existing clients +do not use (as of the time these docs were written, back in 2011). + +## POST Envelope vs. `POST.payload` + + +When this document refers to POST data, it is referring to top-level +object in JSON-format POSTed input data. When we say `POST.payload` we +refer to the "payload" property of the POST data. While fossil's core +handles *form-urlencoded* POST data, if such data is sent in then +parsing it as JSON cannot succeed, which means that (at worst) the +JSON-mode bits will "not see" any POST data. Data POSTed to the JSON API +must be sent non-form-urlencoded (i.e. as plain text). + +Framework-level configuration options are always set via the top-level +POST envelope object or GET parameters. Request-specific options are set +either in `POST.payload` or GET parameters (though the former is required +in some cases). Here is an example which demonstrates the possibly +not-so-obvious difference between the two types of options (framework +vs. request-specific): + +```json +{ +"requestId":"my request", // standard envelope property (optional) +"command": "timeline/wiki", // also standard +"indent":2, // output indention is a framework-level option +"payload":{ // *anything* in the payload is request-specific + "limit":1 +} +} +``` + +When a given parameter is set in two places, e.g. GET and POST, or +POST-from-a-file and CLI parameters, which one takes precedence +depends on the concrete command handler (and may be unspecified). Most +will give precedence to CLI and GET parameters, but POSTed values are +technically preferred for non-string data because no additional "type +guessing" or string-to-whatever conversion has to be made (GET/CLI +parameters are *always* strings, even if they look like a number or +boolean). + + +<a id="request-param-types"></a> +# Request Parameter Data Types + +When parameters are sent in the form of GET or CLI arguments, they are +inherently strings. When they come in from JSON they keep their full +type (boolean, number, etc.). All parameters in this API specify what +*type* (or types) they must (or may) be. For strings, there is no +internal conversion/interpretation needed for GET- or CLI-provided +parameters, but for other types we sometimes have to convert strings to +other atomic types. This section describes how those string-to-whatever +conversions behave. + +No higher-level constructs, e.g. JSON **arrays** or **objects**, are +accepted in string form. Such parameters must be set in the POST +envelope or payload, as specified by the specific API. + +This API does not currently use any **floating-point** parameters, but +does return floating-point results in a couple of places. + +For **integer** parameters we use a conventional string-to-int algorithm +and assume base 10 (analog to atoi(3)). The API may err on the side of +usability when given technically invalid values. e.g. "123abc" will +likely be interpreted as the integer 123. No APIs currently rely on +integer parameters with more than 32 bits (signedness is call-dependent +but few, if any, use negative values). + +**Boolean** parameters are a bit schizophrenic... + +In **CLI mode**, boolean flags do not have a value, per se, and thus +require no string-to-bool conversion. e.g. +`fossil foo -aBoolOpt -non-bool-opt value`. + +Those which arrive as strings via **GET parameters** treat any of the +following as true: a string starting with a character in the set +`[1-9tT]`. All other string values are considered to be false for this +purpose. + +Those which are part of the **POST data** are normally (but not always - +it depends on the exact context) evaluated as the equivalent of +JavaScript booleans. e.g. if we have `POST.envelope.foo="f"`, and evaluate +it as a JSON boolean (as opposed to a string-to-bool conversion), the +result will be true because the underlying JSON API follows JavaScript +semantics for any-type-to-bool conversions. As long as clients always +send "proper" booleans in their POST data, the difference between +GET/CLI-provided booleans should never concern them. + +TODO: consider changing the GET-value-to-bool semantics to match the JS +semantics, for consistency (within the JSON API at least, but that might +cause inconsistencies vis-a-vis the HTML interface). + +<a id="response-envelope"></a> +# Response Envelope + +Every response comes in the form of an HTTP response or (in CLI mode) +JSON sent to stdout. The body of the response is a JSON object following +a common envelope format. The envelope has the following properties: + + +- `fossil`: Fossil server version string. This property is basically + "the official response envelope marker" - if it is set, clients can + "probably safely assume" that the object indeed came from one of the + Fossil/JSON APIs. This API never creates responses which do not + contain this property. +- `requestId`: Only set if the request contained it, and then it is + echoed back to the caller as-is. This can be used to determine + (client-side) which request a given response is coming in for + (assuming multiple asynchronous requests are pending). In practice + this generally isn’t needed because response handling tends to be + done by closures associated with the original request object (at + least in JavaScript code). In languages without closures it might + have some use. It may be any legal JSON value - it need not be + confined to a string or number. +- `resultCode`: Standardized result code string in the form + `FOSSIL-####`. Only error responses contain a `resultCode`. +- `resultText`: Possibly a descriptive string, possibly + empty. Supplements the resultCode, but can also be set on success + responses (but normally isn't). Clients must not rely on any + specific values being set here. +- `payload`: Request-specific response payload (data type/structure is + request-specific). The payload is never set for error responses, + only for success responses (and only those which actually have a + payload - not all do). +- `timestamp`: Response timestamp (GMT Unix Epoch). We use seconds + precision because I did not know at the time that Fossil actually + records millisecond precision. +- `payloadVersion`: Not initially needed, but reserved for future use + in maintaining version compatibility when the format of a given + response type's payload changes. If needed, the "first version" + value is assumed to be 0, for semantic [near-]compatibility with the + undefined value clients see when this property is not set. +- `command`: Normalized form of the command being run. It consists of + the "command" (non-argument) parts of the request path (or CLI + positional arguments), excluding the initial "/json/" part. e.g. the + "command" part of "/json/timeline/checkin?a=b" (CLI: json timeline + checkin...) is "timeline/checkin" (both in CLI and HTTP modes). +- `apiVersion`: Not yet used, but reserved for a numeric value which + represents the JSON API's version (which can be used to determine if + it has a given feature or not). This will not be implemented until + it's needed. +- `warnings`: Reserved for future use as a standard place to put + non-fatal warnings in responses. Will be an array but the warning + structure/type is not yet specified. Intended primarily as a + debugging tool, and will "probably not" become part of the public + client interface. +- `g`: Fossil administrators (those with the "a" or "s" permissions) + may set the `debugFossilG` boolean request parameter (CLI: + `--json-debug-g`) to enable this property for any given response. It + contains a good deal of the server-side internal state at the time + the response was generated, which is often useful in debuggering + problems. Trivia: it is called "g" because that's the name of + fossil's internal global state object. +- `procTimeMs`: For debugging only - generic clients must not rely on + this property. Contains the number of milliseconds the JSON command + processor needed to dispatch and process the command. TODO: move the + timer into the fossil core so that we can generically time its + responses and include the startup overhead in the time calculation. + + + +<a id="http-response-header"></a> +# HTTP Response Headers + +The Content-Type HTTP header of a response will be either +application/json, application/javascript, or text/plain, depending on +whether or not we are in JSONP mode or (failing that) the contents of +the "Accept" header sent in the request. The response type will be +text/plain if it cannot figure out what to do. The response's +Content-Type header *may* contain additional metadata, e.g. it might +look like: application/json; charset=utf-8 + +Apropos UTF-8: note that JSON is, by definition, Unicode and recommends +UTF-8 encoding (which is what we use). That means if your console cannot +handle UTF-8 then using this API in CLI mode might (depending on the +content) render garbage on your screen. + + +<a id="cli-vs-http"></a> +# CLI vs. HTTP Mode + +CLI (command-line interface) and HTTP modes (CGI and standalone server) +are consolidated in the same implementations and behave essentially +identically, with only minor exceptions. + +An HTTP path of `/json/foo` translates to the CLI command `fossil json +foo`. CLI mode takes options in the fossil-convention forms (e.g. `--foo 3` +or `-f 3`) whereas HTTP mode takes them via GET/POST data (e.g. `?foo=1`). +(Note that per long-standing fossil convention CLI parameters taking a +value do not use an equal sign before the value!) + +For example: + +- HTTP: `/json/timeline/wiki?after=2011-09-01&limit=3` +- CLI: `fossil json timeline wiki --after 2011-09-01 --limit 3` + +Some commands may only work in one mode or the other (for various +reasons). In CLI mode the user automatically has full setup/admin +access. + +In HTTP mode, request-specific options can also be specified in the +`POST.payload` data, and doing so actually has an advantage over +specifying them as URL parameters: posting JSON data retains the full +type information of the values, whereas GET-style parameters are always +strings and must be explicitly type-checked/converted (which may produce +unpredictable results when given invalid input). That said, oftentimes +it is more convenient to pass the options via URL parameters, rather +than generate the request envelope and payload required by POST +requests, and the JSON API makes some extra effort to treat GET-style +parameters type-equivalent to their POST counterparts. If a property +appears in both GET and `POST.payload`, GET-style parameters *typically* +take precedence over `POST.payload` by long-standing convention (=="PHP +does it this way by default"). + +(That is, however, subject to eventual reversal because of the +stronger type safety provided by POSTed JSON. Philosophically +speaking, though, GET *should* take precedence, in the same way that +CLI-provided options conventionally override app-configuration-level +options.) + +One notable functional difference between CLI and HTTP modes is that in +CLI mode error responses *might* be accompanied by a non-0 exit status +(they "should" always be, but there might be cases where that does not +yet happen) whereas in HTTP mode we always try to exit with code 0 to +avoid generating an HTTP 500 ("internal server error"), which could keep +the JSON response from being delivered. The JSON code only intentionally +allows an HTTP 500 when there is a serious internal error like +allocation or assertion failure. HTTP clients are expected to catch +errors by evaluating the response object, not the HTTP result code. + +<a id="simulating-post-data"></a> +# Simulating POSTed data + +We have a mechanism to feed request data to CLI mode via +files (simulating POSTed data), as demonstrated in this example: + +```console +$ cat in.json +{ "command": "timeline/wiki", "indent":2, "payload":{"limit":1}} +$ fossil json --json-input in.json # use filename - for stdin +``` + +The above is equivalent to: + +```console +$ echo '{"indent":2, "payload":{"limit":1}}' \ + | fossil json timeline wiki --json-input - +``` + +Note that the "command" JSON parameter is only checked when no json +subcommand is provided on the CLI or via the HTTP request path. Thus we +cannot pass the CLI args "json timeline" in conjunction with a "command" +string of "wiki" this way. + +***HOWEVER...*** + +Much of the existing JSON code was written before the `--json-input` +option was possible. Because of this, there might be some +"misinteractions" when providing request-specific options via *both* +CLI options and simulated POST data. Those cases will eventually be +ironed out (with CLI options taking precedence). Until then, when +"POSTing" data in CLI mode, for consistent/predictible results always +provide any options via the JSON request data, not CLI arguments. That +said, there "should not" be any blatant incompatibilities, but some +routines will prefer `POST.payload` over CLI/GET arguments, so there +are some minor inconsistencies across various commands with regards to +which source (POST/GET/CLI) takes precedence for a given option. The +precedence "should always be the same," but currently cannot be due to +core fossil implementation details (the internal consolidation of +GET/CLI/POST vars into a single set). + + +<a id="json-indentation"></a> +# Indentation/Formatting of JSON Output + +CLI mode accepts the `--indent|-I #` option to set the indention level +and HTTP mode accepts `indent=#` as a GET/POST parameter. The semantics +of the indention level are derived from the underlying JSON library and +have the following meanings: 0 (zero) or less disables all superfluous +indentation (this is the default in HTTP mode). A value of 1 uses 1 hard +TAB character (ASCII 0x09) per level of indention (the default in CLI +mode). Values greater than 1 use that many whitespaces (ASCII 32d) per +level of indention. e.g. a value of 7 uses 7 spaces per level of +indention. There is no way to specify one whitespace per level, but if +you *really* want one whitespace instead of one tab (same data size) you +can filter the output to globally replace ASCII 9dec (TAB) with ASCII +32dec (space). Because JSON string values *never* contain hard tabs +(they are represented by `\t`) there is no chance that such a global +replacement will corrupt JSON string contents - only the formatting will +be affected. + +Potential TODO: because extraneous indention "could potentially" be used +as a form of DoS, the option *might* be subject to later removal from HTTP +mode (in CLI it's fine). + +In HTTP mode no trailing newline is added to the output, whereas in CLI +mode one is normally appended (exception: in JSONP mode no newline is +appended, to (rather pedantically and arbitraily) allow the client to +add a semicolon at the end if he likes). There is currently no option to +control the newline behaviour, but the underlying JSON code supports +this option, so adding it to this API is just a matter of adding the +CLI/HTTP args for it. + +Pedantic note: internally the indention level is stored as a single +byte, so giving large indention values will cause harmless numeric +overflow (with only cosmetic effects), meaning, e.g., 257 will overflow +to the value 1. + +Potential TODO: consider changing cson's indention mechanism to use a +*signed* number, using negative values for tabs and positive for +whitespace count (or the other way around). This would require more +doc changes than code changes :/. + + +<a id="jsonp"></a> +# JSONP + +The API supports JSONP-style output. The caller specifies the callback +name and the JSON response will be wrapped in a function call to that +name. For HTTP mode pass the `jsonp=string` option (via GET or POST +envelope) and for CLI use `--jsonp string`. + +For example, if we pass the JSONP name `myCallback` then a response will +look like: + +```js +myCallback({...response...}) +``` + +Note that fossil does not evaluate the callback name itself, other than +to verify that it is-a string, so "garbage in, garbage out," and all +that. (Remember that CLI and GET parameters are *always* strings, even +if they *look* like numbers.) + + +<a id="result-codes"></a> +# API Result Codes + +Result codes are strings which tell the client whether or not a given +API call succeeded or failed, and if it failed *perhaps* some hint as to +why it failed. + +The result code is available via the resultCode property of every +*error* response envelope. Since having a result code value for success +responses is somewhat redundant, success responses contain no resultCode +property. In practice this simplifies error checking on the client side. + +The codes are strings in the form `FOSSIL-####`, where `####` is a +4-digit integral number, left-padded with zeros. The numbers follow +these conventions: + +- The number 0000 is reserved for the "not an error" (OK) case. Since + success responses do not contain a result code, clients won't see + this value (except in documentation). +- All numbers with a leading 0 are reserved for *potential* future use + in reporting non-fatal warnings. +- Despite *possibly* having leading zeros, the numbers are decimal, + not octal. Script code which uses eval() or similar to produce + integers from them may need to take that into account. +- The 1000ths and 100ths places of the number describe the general + category of the error, e.g. authentication- vs. database- vs. usage + errors. The 100ths place is more specific than the 1000ths place, + allowing two levels of sub-categorization (which "should be enough" + for this purpose). This separation allows the server administrator + to configure the level of granularity of error reporting. e.g. some + admins consider error messages to be security-relevant and like to + "dumb them down" on their way to the client, whereas developers + normally want to see very specific error codes when tracking down a + problem. We can offer a configuration option to "dumb down" error + codes to their generic category by simply doing a modulo 100 + (or 1000) against the native error code number. e.g. FOSSIL-1271 + could (via a simple modulo) be reduced to FOSSIL-1200 or + FOSSIL-1000, depending on the paranoia level of the sysadmin. I have + tried to order the result code numbers so that a dumb-down level of + 2 provides reasonably usable results without giving away too much + detail to malicious clients.\ + (**TODO:** `g.json.errorDetailParanoia` is used to set the + default dumb-down level, but it is currently set at compile-time. + It needs to be moved to a config option. We have a chicken/egg scenario + with error reporting and db access there (where the config is + stored).) +- Once a number is assigned to a given error condition (and actually + used somewhere), it may not be changed/redefined. JSON clients need + to be able to rely on stable result codes in order to provide + adequate error reporting to their clients, and possibly for some + error recovery logic as well (i.e. to decide whether to abort or + retry). + +The *tentative* list of result codes is shown in the following table. +These numbers/ranges are "nearly arbitrarily" chosen except for the +"special" value 0000. + +**Maintenance reminder:** these codes are defined in +[`src/json_detail.h`](/finfo/src/json_detail.h) (enum +`FossilJsonCodes`) and assigned default `resultText` values in +[`src/json.c:json_err_cstr()`](/finfo/src/json.c). Changes there need +to be reflected here (and vice versa). Also, we have assertions in +place to ensure that C-side codes are in the range 1000-9999, so do +not just go blindly change the numeric ranges used by the enum. + + +**`FOSSIL-0###`: Non-error Category** + +- `FOSSIL-0000`: Success/not an error. Succesful responses do not + contain a resultCode, so clients should never see this. +- `FOSSIL-0###`: Reserved for potential future use in reporting + non-fatal warnings. + + + +**`FOSSIL-1000`: Generic Errors Category** + +- `FOSSIL-1101`: Invalid request. Request envelope is invalid or + missing. +- `FOSSIL-1102`: Unknown JSON command. +- `FOSSIL-1103`: Unknown/unspecified error +- `FOSSIL-1104`: RE-USE +- `FOSSIL-1105`: A server-side timeout was reached. (i’m not sure we + can actually implement this one, though.) +- `FOSSIL-1106`: Assertion failed (or would have had we + continued). Note: if an `assert()` fails in CGI/server modes, the HTTP + response will be code 500 (Internal Server Error). We want to avoid + that and return a JSON response instead. All of that said - there seems + to be little reason to implement this, since assertions are "truly + serious" errors. +- `FOSSIL-1107`: Allocation/out of memory error. This cannot be reasonably + reported because fossil aborts if an allocation fails. +- `FOSSIL-1108`: Requested API is not yet implemented. +- `FOSSIL-1109`: Panic! Fossil's `fossil_panic()` or `cgi_panic()` was + called. In non-JSON HTML mode this produces an HTTP 500 + error. Clients "should" report this as a potential bug, as it + "possibly" indicates that the C code has incorrect argument- or + error handling somewhere. +- `FOSSIL-1110`: Reading of artifact manifest failed. Time to contact + your local fossil guru. +- `FOSSIL-1111`: Opening of file failed (e.g. POST data provided to + CLI mode). + + +**`FOSSIL-2000`: Authentication/Access Error Category** + +- `FOSSIL-2001`: Privileged request was missing authentication + token/cookie. +- `FOSSIL-2002`: Access to requested resource was denied. Oftentimes + the `resultText` property will contain a human-language description of + the access rights needed for the given command. +- `FOSSIL-2003`: Requested command is not available in the current + operating mode. Returned in CLI mode by commands which require HTTP + mode (e.g. login), and vice versa. FIXME: now that we can simulate + POST in CLI mode, we can get rid of this distinction for some of the + commands. +- `FOSSIL-2100`: Login Failed. +- `FOSSIL-2101`: Anonymous login attempt is missing the + "anonymousSeed" property (fetched via [the `/json/anonymousPassword` + request](api-auth.md#login-anonymous)). Note that this is more + specific form of `FOSSIL-3002`. + + +ONLY FOR TESTING purposes should the remaning 210X sub-codes be +enabled (they are potentially security-relevant, in that the client +knows which part of the request was valid/invalid): + +- `FOSSIL-2102`: Name not supplied in login request +- `FOSSIL-2103`: Password not supplied in login request +- `FOSSIL-2104`: No name/password match found + + +**`FOSSIL-3000`: Usage Error Category** + +- `FOSSIL-3001`: Invalid argument/parameter type(s) or value(s) in + request +- `FOSSIL-3002`: Required argument(s)/parameter(s) missing from + request +- `FOSSIL-3003`: Requested resource identifier is ambiguous (e.g. a + shortened hash that matches multiple artifacts, an abbreviated + date that matches multiple commits, etc.) +- `FOSSIL-3004`: Unresolved resource identifier. A branch/tag/uuid + provided by client code could not be resolved. This is a special + case of #3006. +- `FOSSIL-3005`: Resource already exists and overwriting/replacing is + not allowed. e.g. trying to create a wiki page or user which already + exists. FIXME? Consolidate this and resource-not-found into a + separate category for dumb-down purposes? +- `FOSSIL-3006`: Requested resource not found. e.g artifact ID, branch + name, etc. + + +**`FOSSIL-4000`: Database-related Error Category** + +- `FOSSIL-4001`: Statement preparation failed. +- `FOSSIL-4002`: Parameter binding failed. +- `FOSSIL-4003`: Statement execution failed. +- `FOSSIL-4004`: Database locked (this is not used anywhere, but + reserved for future use). + +Special-case DB-related errors... + +- `FOSSIL-4101`: Fossil Schema out of date (repo rebuild required). +- `FOSSIL-4102`: Fossil repo db could not be found. +- `FOSSIL-4103`: Repository db is not valid (possibly corrupt). +- `FOSSIL-4104`: Check-out not found. This is similar to FOSSIL-4102 + but indicates that a local checkout is required (but was not + found). Note that the 4102 gets triggered earlier than this one, and + so can appear in cases when a user might otherwise expect a 4104 + error. + + +Some of those error codes are of course "too detailed" for the client to +do anything with (e.g.. 4001-4004), but their intention is to make it +easier for Fossil developers to (A) track down problems and (B) support +clients who report problems. If a client reports, "I get a FOSSIL-4000, +how can I fix it?" then the developers/support personnel can't say much +unless they know if it's a 4001, 4002, 4003, 4004, or 4101 (in which +case they can probably zero in on the problem fairly quickly, since they +know which API call triggered it and they know (from the error code) the +general source of the problem). + +## Why Standard/Immutable Result Codes are Important + +- They are easily internationalized (i.e. associated with non-English + error text) +- Clients may be able to add automatic retry strategies for certain + problem types by examining the result code. e.g. if fossil returns a + locking or timeout error \[it currently does no special + timeout/locking handling, by the way\] the client could re-try, + whereas a usage error cannot be sensibly retried with the same + inputs. +- The "category" structure described above allows us some degree of + flexibility in how detailed the reported errors are reported. +- While the string prefix "FOSSIL-" on the error codes may seem + superfluous, it has one minor *potential* advantage on the client + side: when managing several unrelated data sources, these error + codes can be immediately identified (by higher-level code which may + be ignorant of the data source) as having come from the fossil API. + Think "ORA-111" vs. "111". |