| | @@ -0,0 +1,962 @@ |
| 1 | +ost Requests](#http-postt code). In languages without closures it might
|
| 2 | + have some use. It may be any legal JSON value - it need not be
|
| 3 | + confined to a string or number.
|
| 4 | +- `resultCode`: Standardized result code string in the form
|
| 5 | + `FOSSIL-####`. Only error responses contain a `resultCode`.
|
| 6 | +- `resultText`: Possibly a descriptive string, possibly
|
| 7 | + empty. Supplements the resultCode, but can also be set on success
|
| 8 | + responses (but normally isn't). Clients must not rely on any
|
| 9 | + specific values being set here.
|
| 10 | +- `payload`: Request-specific response payload (data type/structure is
|
| 11 | + request-specific). The payload is never set for error responses,
|
| 12 | + only for success responses (and only those which actually have a
|
| 13 | + payload - not all do).
|
| 14 | +- `timestamp`: Response timestamp (GMT Unix Epoch). We use seco:
|
| 15 | +
|
| 16 | +- `httpo stdout. The body of the response is a JSON object following
|
| 17 | +a common envelope format. The enveAfter several discussions, trties:
|
| 18 | +
|
| 19 | +
|
| 20 | +- `fossil
|
| 21 | +: Fossil server vers basically
|
| 22 | + "the offic
|
| 23 | +compared to the ng tained it, and then it is
|
| 24 | +to unify that an be used to determine
|
| 25 | + (client-side) which request a given response is coming in for
|
| 26 | + (assuming multiple asynchronous requests are pending). In practice
|
| 27 | + this generally isn’t needed because response handling tends to be
|
| 28 | + done by closures associated with the original request object (at
|
| 29 | + least in JavaScript code). In languages without closures it might
|
| 30 | + have some use. It may be any legal JSON value - it need not be
|
| 31 | + confined to a string or number.
|
| 32 | +- `resultCode`: Standardized result code string in the form
|
| 33 | + `FOSSIL-####`. Only error responses contain a `resultCode`.
|
| 34 | +- `resultText`: Possibly a descriptive string, possibly
|
| 35 | + empty. Supplements the resultCode, but can also be set on success
|
| 36 | + responses (bu(TODO: convert to a simple list...)
|
| 37 | +`+-----------------------------------+-----------------------------------+
|
| 38 | +| requestId |responses (but normally isn't). |
|
| 39 | +| ny
|
| 40 | + specific values bei returned |
|
| 41 | +| n: in JSONP mode no newline is
|
| 42 | +appended, tisuccess responses contain no i little reason totype/struc |
|
| 43 | +| nse payload (data type/str command |
|
| 44 | +| ple asynchronous requ
|
| 45 | +sts are pending). In practice
|
| 46 | + this generally isn’t needed because response handling tends to bot rely on any
|
| 47 | + specific val |
|
| 48 | +| onses,
|
| 49 | + only fo. Note that |
|
| 50 | +| | subpaths do *not* work this way. |
|
| 51 | +| |payload (data type/structure is
|
| 52 | + |
|
| 53 | +| ecific). The payload is never set for error responses,
|
| 54 | + only for success responses (and only those which actually have a
|
| 55 | + payload - not all do).
|
| 56 | +- `timestamp`: Response timestamp (GMT Unix Epoch). We use seconds
|
| 57 | + precision because ivelope
|
| 58 | +
|
| 59 | +Every response comes in the form of an HTTP response or (in CLI mode)
|
| 60 | +JSON sent to stdout. The body of the response is a JSON object following
|
| 61 | +a common envelope format. The envelope has the following properties:
|
| 62 | +
|
| 63 | +
|
| 64 | +- `fossil`: Fossil server version string. This property is basically
|
| 65 | + "the official response envelope marker" - if it is using tained it, and then it is
|
| 66 | + echoed back to the caller as-is. This can be used to determine
|
| 67 | + (client-side) which request a given response is coming in for
|
| 68 | + (assuming multiple asynchronous requests are pending). In practice
|
| 69 | + this generally isn’t needed because response handling tends to be
|
| 70 | + done by closures associated with the original request object (at
|
| 71 | + least in JavaScript code). In languages without closures it might
|
| 72 | + have some use. It may be any legal JSON value - it need not be
|
| 73 | + confined to a string or number.
|
| 74 | +- `resultCode`: Standardized result code string in the form
|
| 75 | + `FOSSIL-####`. Only error responses contain a `resultCode`.
|
| 76 | +- `resultText`: Possibly a descriptive string, possibly
|
| 77 | + empty. Supplements the resultCode, but can also be set on success
|
| 78 | + responses (but normally isn't). Clients must not rely on any
|
| 79 | + specific values being set here.
|
| 80 | +- `payload`: Request-specific response payload (data type/structure is
|
| 81 | + request-specific). The payload is never set for error responses,
|
| 82 | + only for success responses (and only those which actually have a
|
| 83 | + payload - not all do).
|
| 84 | +- `timestamp`: Response timestamp (GMT Unix Epoch). We use seconds
|
| 85 | + precision because I did not know at the time that Fossil actually
|
| 86 | + records millisecond precision.
|
| 87 | +- `payloadVersion`: Not initially needed, but reserved for future use
|
| 88 | + in maintaining version compatibility when the format of a given
|
| 89 | + response type's payload changes. If needed, the "first version"
|
| 90 | + value is assumed to be 0, for semantic [near-]compatibility with the
|
| 91 | + undefined value clients see when this property is not set.
|
| 92 | +- `command`: Normalized form of the command being run. It consists of
|
| 93 | + the "command" (non-argument) parts of the request path (or CLI
|
| 94 | + positional arguments), excluding the initial "/json/" part. e.g. the
|
| 95 | + "command" part of "/json/timeline/checkin?a=b" (CLI: json timeline
|
| 96 | + checkin...) is "timeline/checkin" (both in CLI and HTTP modes).
|
| 97 | +- `apiVersion`: Not yet used, but reserved for a numeric value which
|
| 98 | + represents the JSON API's version (which can be used to determine if
|
| 99 | + it has a given feature or not). This will not be implemented until
|
| 100 | + it's needed.
|
| 101 | +- `warnings`: Reserved for future use as a standard place to put
|
| 102 | + non-fatal warnings in responses. Will be an array but the warning
|
| 103 | + structure/type is not yet specified. Intended primarily as a
|
| 104 | + debugging tool, and will "probably not" become part of the public
|
| 105 | + client interface.
|
| 106 | +- `g`: Fossil administrators (those with the "a" or "s" permissions)
|
| 107 | + may set the `debugFossilG` boolean request parameter (CLI:
|
| 108 | + `--json-debug-g`) to enable this property for any given response. It
|
| 109 | + contains a good deal of the server-side internal state at the time
|
| 110 | + the response was generated, which is often useful in debuggering
|
| 111 | + problems. Trivia: it is called "g" because that's the name of
|
| 112 | + fossil's internal global state object.
|
| 113 | +- `procTimeMs`: For debugging only - generic clients must not rely on
|
| 114 | + this property. Contains the number of milliseconds the JSON command
|
| 115 | + processor needed to dispatch and process the command. TODO: move the
|
| 116 | + timer into the fossil core so that we can generically time its
|
| 117 | + responses and include the startup overhead in the time calculation.
|
| 118 | +
|
| 119 | +
|
| 120 | +
|
| 121 | +<a id="http-response-header"></a>
|
| 122 | +# HTTP Response Headers
|
| 123 | +
|
| 124 | +The Content-Type HTTP header of a response will be either
|
| 125 | +application/json, application/javascript, or text/plain, depending on
|
| 126 | +whether or not we are in JSONP mode or (failing that) the contents of
|
| 127 | +the "Accept" header sent in the request. The response type will be
|
| 128 | +text/plain if it cannot figure out what to do. The response's
|
| 129 | +Content-Type header *may* contain additional metadata, e.g. it might
|
| 130 | +look like: application/json; charset=utf-8
|
| 131 | +
|
| 132 | +Apropos UTF-8: note that JSON is, by definition, Unicode and recommends
|
| 133 | +UTF-8 encoding (which is what we use). That means if your console cannot
|
| 134 | +handle UTF-8 then using this API in CLI mode might (depending on the
|
| 135 | +content) render garbage on your screen.
|
| 136 | +
|
| 137 | +
|
| 138 | +<a id="cli-vs-http"></a>
|
| 139 | +# CLI vs. HTTP Mode
|
| 140 | +
|
| 141 | +CLI (command-line interface) and HTTP modes (CGI and standalone server)
|
| 142 | +are consolidated in the same implementations and behave essentially
|
| 143 | +identically, with only minor exceptions.
|
| 144 | +
|
| 145 | +An HTTP path of `/json/foo` translates to the CLI command `fossil json
|
| 146 | +foo`. CLI mode takes options in the fossil-convention forms (e.g. `--foo 3`
|
| 147 | +or `-f 3`) whereas HTTP mode takes them via GET/POST data (e.g. `?foo=1`).
|
| 148 | +(Note that per long-standing fossil convention CLI parameters taking a
|
| 149 | +value do not use an equal sign before the value!)
|
| 150 | +
|
| 151 | +For example:
|
| 152 | +
|
| 153 | +- HTTP: `/json/timeline/wiki?after=2011-09-01&limit=3`
|
| 154 | +- CLI: `fossil json timeline wiki --after 2011-09-01 --limit 3`
|
| 155 | +
|
| 156 | +Some commands may only work in one mode or the other (for various
|
| 157 | +reasons). In CLI mode the user automatically has full setup/admin
|
| 158 | +access.
|
| 159 | +
|
| 160 | +In HTTP mode, request-specific optionapplication/json orm of the comover
|
| 161 | +specifying them as URL parameters: posting JSON data retains the full
|
| 162 | +typetext/plain-style parameters are alapplication/jsonrs are always
|
| 163 | +strings a do
|
| 164 | +not useven invalid input). That said, oftentimes
|
| 165 | +it is more convenient to pass the options via URL parameters, rather
|
| 166 | +than generate the request envelope and payload required by POST
|
| 167 | +requests, and the JSON API makes some extra effort to treat GET-style
|
| 168 | +parameters type-equivalent to their POST counterparts. If a property
|
| 169 | +appears in both GET and `POST.payload`, GET-style parameters *typically*
|
| 170 | +take precedence over `POST.payload` by long-standing convention (=="PHP
|
| 171 | +does it this way by default").
|
| 172 | +
|
| 173 | +(That is, however, subject to eventual reversal because of the
|
| 174 | +stronger type safety provided by POSTed JSON. Philosophically
|
| 175 | +speaking, though, GET *should* take precedence, in the same way that
|
| 176 | +CLI-provided options conventionally override app-configuration-level
|
| 177 | +options.)
|
| 178 | +
|
| 179 | +One notable functional difference between CLI and HTTP modes is that in
|
| 180 | +CLI mode error responses *might* be accompanied by a non-0 exit status
|
| 181 | +(they "should" always be, but there might be cases where that does not
|
| 182 | +yet happen) whereas in HTTP mode we always try to exit with code 0 to
|
| 183 | +avoid generating an HTTP 500 ("internal server error"), which could keep
|
| 184 | +the JSON response from being delivered. The JSON code only intentionally
|
| 185 | +allows an HTTP 500 when there is a serious internal error like
|
| 186 | +allocation or assertion failure. HTTP clients are expected to catch
|
| 187 | +errors by evaluating the response object, not the HTTP result code.
|
| 188 | +
|
| 189 | +<a id="simulating-post-data"></a>
|
| 190 | +# Simulating POSTed data
|
| 191 | +
|
| 192 | +We have a mechanism to feed request data to CLI mode via
|
| 193 | +files (simulating POSTed data), as demonstrated in this example:
|
| 194 | +
|
| 195 | +```console
|
| 196 | +$ cat in.json
|
| 197 | +{ "command": "timeline/wiki", "indent":2, "payload":{"limit":1}}
|
| 198 | +$ fossil json --json-input in.json # use filename - for stdin
|
| 199 | +```
|
| 200 | +
|
| 201 | +The above is equivalent to:
|
| 202 | +
|
| 203 | +```console
|
| 204 | +$ echo '{"indent":2, "payload":{"limit":1}}' \
|
| 205 | + | fossil json timeline wiki --json-input -
|
| 206 | +```
|
| 207 | +
|
| 208 | +Note that the "command" JSON parameter is only checked when no json
|
| 209 | +subcommand is provided on the CLI or via the HTTP request path. Thus we
|
| 210 | +cannot pass the CLI args "json timeline" in conjunction with a "command"
|
| 211 | +string of "wiki" this way.
|
| 212 | +
|
| 213 | +***HOWEVER...***
|
| 214 | +
|
| 215 | +Much of the existing JSON code was written before the `--json-input`
|
| 216 | +option was possible. Because of this, there might be some
|
| 217 | +"misinteractions" when providing request-specific options via *both*
|
| 218 | +CLI options and simulated POST data. Those cases will eventually be
|
| 219 | +ironed out (with CLI options taking "POSTing" data in CLI edble results always
|
| 220 | +provide any options via the JSON request data, not CLI arguments. That
|
| 221 | +said, there "should not" be any blatant incompatibilities, but some
|
| 222 | +routines will prefer `POST.payload` over CLI/GET arguments, so there
|
| 223 | +are some minor inconsistencies across various commands with regards to
|
| 224 | +which source (POST/GET/CLI) takes precedence for a given option. The
|
| 225 | +precedence "should always be the same," but currently cannot be due to
|
| 226 | +core fossil implementation details (the internal consolidation of
|
| 227 | +GET/CLI/POST vars into a single set).
|
| 228 | +
|
| 229 | +
|
| 230 | +<a id="json-indentation"></a>
|
| 231 | +# Indentation/Formatting of JSON Output
|
| 232 | +
|
| 233 | +CLI mode accepts the `--indent|-I #` option to set the indention level
|
| 234 | +and HTTP mode accepts `indent=#` as a GET/POST parameter. The semantics
|
| 235 | +of the indention level are derived from the underlying JSON library and
|
| 236 | +have the following meanings: 0 (zero) or less disables all superfluous
|
| 237 | +indentation (this is the default in HTTP mode). A value of 1 uses 1 hard
|
| 238 | +TAB character (ASCII 0x09) per level of indention (the default in CLI
|
| 239 | +mode). Values greater than 1 use that many whitespaces (ASCII 32d) per
|
| 240 | +level of indention. e.g. a value of 7 uses 7 spaces per level of
|
| 241 | +indention. There is no way to specify one whitespace per level, but if
|
| 242 | +you *really* want one whitespace instead of one tab (same data size) you
|
| 243 | +can filter the output to globally replace ASCII 9dec (TAB) with ASCII
|
| 244 | +32dec (space). Because JSON string values *never* contain hard tabs
|
| 245 | +(they are represented by `\t`) there is no chance that such a global
|
| 246 | +replacement will corrupt JSON string contents - only the formatting will
|
| 247 | +be affected.
|
| 248 | +
|
| 249 | +Potential TODO: because extraneous indention "could potentially" be used
|
| 250 | +as a form of DoS, the option *might* be subject to later removal from HTTP
|
| 251 | +mode (in CLI it's fine).
|
| 252 | +
|
| 253 | +In HTTP mode no trailing newline is added to the output, whereas in CLI
|
| 254 | +mode one is normally appended (exception: in JSONP mode no newline is
|
| 255 | +appended, tisuccess responses contain no i little reason to implement this, since assertions are "truly
|
| 256 | + serious" errors.
|
| 257 | +- `FOSSIL-1107`: Allocation/out of memory error. This cannot be reasonably
|
| 258 | + reported because fossil aborts if an allocation fails.
|
| 259 | +- `FOSSIL-1108`: Requested API is not yet implemented.
|
| 260 | +- `FOSSIL-1109`: Panic! Fossil's `fossil_panic()` or `cgi_panic()` was
|
| 261 | + called. In non-JSON HTML mode this produces an HTTP 500
|
| 262 | + error. Clients "should" report this as a potential bug, as it
|
| 263 | + "possibly" indicates that the C code has incorrect argument- or
|
| 264 | + error handling somewhere.
|
| 265 | +- `FOSSIL-1110`: Reading of artifact manifest failed. Time to contact
|
| 266 | + your local fossil guru.
|
| 267 | +- `FOSSIL-1111`: Opening of file failed (e.g. POST data provided to
|
| 268 | + CLI mode).
|
| 269 | +
|
| 270 | +
|
| 271 | +**`FOSSIL-2000`: Authentication/Access Error Category**
|
| 272 | +
|
| 273 | +- `FOSSIL-2001`: Privileged request was missing authentication
|
| 274 | + token/cookie.
|
| 275 | +- `FOSSIL-2002`: Access to requested resource was denied. Oftentimes
|
| 276 | + the `resultText` property will contain a human-language description of
|
| 277 | + the access rights needed for the given command.
|
| 278 | +- `FOSSIL-2003`: Requested command is not available in the current
|
| 279 | + operating mode. Returned in CLI mode by commands which require HTTP
|
| 280 | + mode (e.g. login), and vice versa. FIXME: now that we can simulate
|
| 281 | + POST in CLI mode, we can get rid of this distincuse the debugFossilG Login Failed.
|
| 282 | +- `FOSSIL-2101`: Ano--json-debug-g-2101`: Anonymous login attempt is missing the
|
| 283 | + "anonymousSeed" property (fetched via [the `/json/anonymousPassword`
|
| 284 | + request](api-auth.md#login-anonymous)). Note that this is more
|
| 285 | + specific form of `FOSSIL-3002`.
|
| 286 | +
|
| 287 | +
|
| 288 | +ONLY FOR TESTING purposes should the remaning 210X sub-codes be
|
| 289 | +enabled (they are potentially security-relevant, in that the client
|
| 290 | +knows which part of the request was valid/invalid):
|
| 291 | +
|
| 292 | +- `FOSSIL-2102`: Name not supplied in login request
|
| 293 | +- `FOSSIL-2103`: Password not supplied in login request
|
| 294 | +- `FOSSIL-2104`: No name/password match found
|
| 295 | +
|
| 296 | +
|
| 297 | +**`FOSSIL-3000`: Usage Error Category**
|
| 298 | +
|
| 299 | +- `FOSSIL-3001`: Invalid argument/parameter type(s) or value(s) in
|
| 300 | + request
|
| 301 | +- `FOSSIL-3002`: Required argument(s)/parameter(s) missing from
|
| 302 | + request
|
| 303 | +- `FOSSIL-3003`: Requested resource identifier is ambiguous (e.g. a
|
| 304 | + shortened hash that matches multiple artifacts, an abbreviated
|
| 305 | + date that matches multiple commits, etc.)
|
| 306 | +- `FOSSIL-3004`: Unresolved resource identifier. A branch/tag/uuid
|
| 307 | + provided by client code could not be resolved. This is a special
|
| 308 | + case of #3006.
|
| 309 | +- `FOSSIL-3005`: Resource already exists and overwriting/replacing is
|
| 310 | + not allowed. e.g. trying to create a wiki page or user which already
|
| 311 | + exists. FIXME? Consolidate this and resource-not-found into a
|
| 312 | + separate category for dumb-down purposes?
|
| 313 | +- `FOSSIL-3006`: Requested resource not found. e.g artifact ID, branch
|
| 314 | + name, etc.
|
| 315 | +
|
| 316 | +
|
| 317 | +**`FOSSIL-4000`: Database-related Error Category**
|
| 318 | +
|
| 319 | +- `FOSSIL-4001`: Statement preparation failed.
|
| 320 | +- `FOSSIL-4002`: Parameter binding failed.
|
| 321 | +- `FOSSIL-4003`: Statement execution failed.
|
| 322 | +- `FOSSIL-4004`: Database locked (this is not used anywhere, but
|
| 323 | + reserved for future use).
|
| 324 | +
|
| 325 | +Special-case DB-related errors...
|
| 326 | +
|
| 327 | +- `FOSSIL-4101`: Fossil Schema out of date (repo rebuild required).
|
| 328 | +- `FOSSIL-4102`: Fossil repo db could not be found.
|
| 329 | +- `FOSSIL-4103`: Repository db is not valid (possibly corrupt).
|
| 330 | +- `FOSSIL-4104`: Check-out not found. This is similar to FOSSIL-4102
|
| 331 | + but indicates that a local checkout is required (but was not
|
| 332 | + found). Note that the 4102 gets triggered earlier than this one, and
|
| 333 | + so can appear in cases when a user might otherwise expect a 4104
|
| 334 | + error.
|
| 335 | +
|
| 336 | +
|
| 337 | +Some of those error codes are of course "too detailed" for the client to
|
| 338 | +do anything with (e.g.. 4001-4004), but their intention is to make it
|
| 339 | +easier for Fossil developers to (A) track down problems and (B) support
|
| 340 | +clients who report problems. If a client reports, "I get a FOSSIL-4000,
|
| 341 | +how can I fix it?" then the developers/support personnel can't say much
|
| 342 | +unless they know if it's a 4001, 4002, 4003, 4004, or 4101 (in which
|
| 343 | +case they can probably zero in on the problem fairly quickly, since they
|
| 344 | +know which API call triggered it and they know (from the error code) the
|
| 345 | +general source of the problem).
|
| 346 | +
|
| 347 | +## Why Standard/Immutable Result Codes are Important
|
| 348 | +
|
| 349 | +- They are easily internationalized (i.e. associated with non-English
|
| 350 | + error text)
|
| 351 | +- Clients may be able to add automatic retry strategies for certain
|
| 352 | + problem types by examining the result code. e.g. if fossil returns a
|
| 353 | + locking or timeout error \[it currently does no special
|
| 354 | + timeout/locking handling, by the way\] the client could re-try,
|
| 355 | + whereas a usage error cannot be sensibly retried with the same
|
| 356 | + inputs.
|
| 357 | +- The "category" structure described above allows us some degree of
|
| 358 | + flexibility in how detailed the reported errors are reported.
|
| 359 | +- While the string prefix "FOSSIL-" on the error codes may seem
|
| 360 | + superfluous, it has one minor *potential* advantage on the client
|
| 361 | + side: when managing several unrelated data sources, these error
|
| 362 | + codes can be immediately identified (by higher-level code which may
|
| 363 | + be ignorant of the data source) as having comUUID can be ambiguous).the form
|
| 364 | + `FOSSIL-####`. Only error responses contain a `resultCode`.
|
| 365 | +- `resultText`: Possibly a descriptive string, possibly
|
| 366 | + empty. Supplements the resultCode, but can also be set on success
|
| 367 | + responses (but normally isn't). Clients must not rely on any
|
| 368 | + specific values being set here.
|
| 369 | +- `payload`: Request-specific response payload (data type/structure is
|
| 370 | + request-specific). The payload is never set for error responses,
|
| 371 | + only for success responses (and only those which actually have a
|
| 372 | + payload - not all do).
|
| 373 | +- `timestamp`: Response timestamp (GMT Unix Epoch). We use seconds
|
| 374 | + precision because ivelope
|
| 375 | +
|
| 376 | +Every response comes in the form of an HTTP response or (in CLI mode)
|
| 377 | +JSON sent to stdout. The body of the response is a JSON object following
|
| 378 | +a common envelope format. The envelope has the following properties:
|
| 379 | +
|
| 380 | +
|
| 381 | +- `fossil`: Fossil server version string. This property is basically
|
| 382 | + "the official response envelope marker" - if it is set, clients can
|
| 383 | + "probably safely assume" that the object indeed came from one of the
|
| 384 | + Fossil/JSON APIs. This API never creates responses which do not
|
| 385 | + contain this property.
|
| 386 | +- `requestId`: Only ple asynchronous requ
|
| 387 | +sts are pending). In practice
|
| 388 | + this generally isn’t needed because response handling tends to be
|
| 389 | + done by closures associated with the original request object (at
|
| 390 | + least in JavaScript code). In languages without closures it might
|
| 391 | + have some use. It may be any legal JSON value - it need not be
|
| 392 | + confined to a string or number.
|
| 393 | +- `resultCode`: Standardized result code string in the form
|
| 394 | + `FOSSIL-####`. Only error responses contain a `resultCode`.
|
| 395 | +- `resultText`: Possibly a descriptive string, possibly
|
| 396 | + empty. Supplements the resultCode, but can also be set on success
|
| 397 | + responses (but normally isn't). Clients must not rely on any
|
| 398 | + specific values being set here.
|
| 399 | +- `payload`: Request-specific response payload (data type/structure is
|
| 400 | + request-specific). The payload is never set for error responses,
|
| 401 | + only for success responses (and only those which actually have a
|
| 402 | + payload - not all do).
|
| 403 | +- `timestamp`: Response timestamp (GMT Unix Epoch). We use seconds
|
| 404 | + precision because ivelope
|
| 405 | +
|
| 406 | +Every response comes in the form of an HTTP response or (in CLI mode)
|
| 407 | +JSON sent to stdout. The body of the response is a JSON object following
|
| 408 | +a common envelope format. The envelope has the following properties:
|
| 409 | +
|
| 410 | +
|
| 411 | +- `fossil`: Fossil server version string. This property is basically
|
| 412 | + "the official response envelope marker" - if it is set, clients can
|
| 413 | + "probably safely assume" that the object indeed came from one of the
|
| 414 | + Fossil/JSON APIs. This API never creates responses which do not
|
| 415 | + contain this property.
|
| 416 | +- `requestId`: Only set if the request contained it, and then it is
|
| 417 | + echoed back to the caller as-is. This can be used to determine
|
| 418 | + (client-side) which request a given response is coming in for
|
| 419 | + (assuming multiple asynchronous requests are pending). In practice
|
| 420 | + this generally isn’t needed because response handling tends to be
|
| 421 | + done by closures associated with the original request object (at
|
| 422 | + least in JavaScript code). In languages without closures it might
|
| 423 | + have some use. It may be any legal JSON value - it need not be
|
| 424 | + confined to a string or number.
|
| 425 | +- `resultCode`: Standardized result code string in the form
|
| 426 | + `FOSSIL-####`. Only error responses contain a `resultCode`.
|
| 427 | +- `resultText`: Possibly a descriptive string, possibly
|
| 428 | + empty. Supplements the resultCode, but can also be set on success
|
| 429 | + responses (but normally isn't). Clients must not rely on any
|
| 430 | + specific values being set here.
|
| 431 | +- `payload`: Request-specific response payload (data type/structure is
|
| 432 | + request-specific). The payload is never set for error responses,
|
| 433 | + only for success responses (and only those which actually have a
|
| 434 | + payload - not all do).
|
| 435 | +- `timestamp`: Response timestamp (GMT Unix Epoch). We use seconds
|
| 436 | + precision because I did not know at the time that Fossil actually
|
| 437 | + records millisecond precision.
|
| 438 | +- `payloadVersion`: Not initially needed, but reserved for future use
|
| 439 | + in maintaining version compatibility when the format of a given
|
| 440 | + response type's payload changes. If needed, the "first version"
|
| 441 | + value is assumed to be 0, for semantic [near-]compatibility with the
|
| 442 | + undefined value clients see when this property is not set.
|
| 443 | +- `command`: Normalized form of the command being run. It consists of
|
| 444 | + the "command" (non-argument) parts of the request path (or CLI
|
| 445 | + positional arguments), excluding the initial "/json/" part. e.g. the
|
| 446 | + "command" part of "/json/timeline/checkin?a=b" (CLI: json timeline
|
| 447 | + checkin...) is "timeline/checkin" (both in CLI and HTTP modes).
|
| 448 | +- `apiVersion`: Not yet used, but reserved for a numeric value which
|
| 449 | + represents the JSON API's version (which can be used to determine if
|
| 450 | + it has a given feature or not). This will not be implemented until
|
| 451 | + it's needed.
|
| 452 | +- `warnings`: Reserved for future use as a standard placehref- `resultCode`: Standardized result code string in the form
|
| 453 | + `FOSSIL-####`. Only error responses contain a `resultCode`.
|
| 454 | +- `resultText`: Possibly a descriptive string, possibly
|
| 455 | + empty. Supplements the resultCode, but can also be set on success
|
| 456 | + responses (but normally isn't). Clients must not rely on any
|
| 457 | + specific values being set here.
|
| 458 | +- `payload`: Request-specific response payload (data type/structure is
|
| 459 | + request-specific). The payload is never set for error responses,
|
| 460 | + only for success responses (and only those which actually have a
|
| 461 | + payload - not all do).
|
| 462 | +- `timestamp`: Response timestamp (GMT Unix Epoch). We use seconds
|
| 463 | + precision because I did not know at the time that Fossil actually
|
| 464 | + records millisecond precision.
|
| 465 | +- `payloadVersion`: Not initially needed, but reserved for future use
|
| 466 | + in maintaining version compatibility when the format of a given
|
| 467 | + response type's payload changes. If needed, the "first version"
|
| 468 | + value is assumed to be 0, for semantic [near-]compatibility with the
|
| 469 | + undefined value clients see when this property is not set.
|
| 470 | +- `command`: Normalized form of the command being run. It consists of
|
| 471 | + the "command" (non-argument) parts of the request path (or CLI
|
| 472 | + positional arguments), excluding the initial "/json/" part. e.g. the
|
| 473 | + "command" part of "/json/timeline/checkin?a=b" (CLI: json timeline
|
| 474 | + checkin...) is "timeline/checkin" (both in CLI and HTTP modes).
|
| 475 | +- `apiVersion`: Not yet used, but reserved for a numeric value which
|
| 476 | + represents the JSON API's version (which can be used to determine if
|
| 477 | + it has a given feature or not). This will not be implemented until
|
| 478 | + it's needed.
|
| 479 | +- `warnings`: Reserved for future use as a standard place to put
|
| 480 | + non-fatal warnings in responses. Will be an array but the warning
|
| 481 | + structure/type is not yet specified. Intended primarily as a
|
| 482 | + debugging tool, and will "probably not" become part of the public
|
| 483 | + client interface.
|
| 484 | +- `g`: Fossil administrators (those with the "a" or "s" permissions)
|
| 485 | + may set the `debugFossilG` boolean request parameter (CLI:
|
| 486 | + `--json-debug-g`) to enable this property for any given response. It
|
| 487 | + contains a good deal of the server-side internal state at the time
|
| 488 | + the response was generated, which is often useful in debuggering
|
| 489 | + problems. Trivia: it is called "g" because that's the name of
|
| 490 | + fossil's internal global state object.
|
| 491 | +- `procTimeMs`: For debugging only - generic clients must not rely on
|
| 492 | + this property. Contains the number of milliseconds the JSON command
|
| 493 | + processor needed to dispatch and process the command. TODO: move the
|
| 494 | + timer into the fossil core so that we can generically time its
|
| 495 | + responses and include the startup overhead in the time calculation.
|
| 496 | +
|
| 497 | +
|
| 498 | +
|
| 499 | +<a id="http-response-header"></a>
|
| 500 | +# HTTP Response Headers
|
| 501 | +
|
| 502 | +The Content-Type HTTP header of a response will be either
|
| 503 | +application/json, application/javascript, or text/plain, depending on
|
| 504 | +whether or not we are in JSONP mode or (failing that) the contents of
|
| 505 | +the "Accept" header sent in the request. The response type will be
|
| 506 | +text/plain if it cannot figure out what to do. The response's
|
| 507 | +Content-Type header *may* contain additional metadata, e.g. it might
|
| 508 | +look like: application/json; charset=utf-8
|
| 509 | +
|
| 510 | +Apropos UTF-8: note that JSON is, by definition, Unicode and recommends
|
| 511 | +UTF-8 encoding (which is what we use). That means if your console cannot
|
| 512 | +handle UTF-8 then using this API in CLI mode might (depending on the
|
| 513 | +content) render garbage on your screen.
|
| 514 | +
|
| 515 | +
|
| 516 | +<a id="cli-vs-http"></a>
|
| 517 | +# CLI vs. HTTP Mode
|
| 518 | +
|
| 519 | +CLI (command-line interface) and HTTP modes (CGI and standalone server)
|
| 520 | +are consolidated in the same implementations and behave essentially
|
| 521 | +identically, with only minor exceptions.
|
| 522 | +
|
| 523 | +An HTTP path of `/json/foo` translates to the CLI command `fossil json
|
| 524 | +foo`. CLI mode takes options in the fossil-convention forms (e.g. `--foo 3`
|
| 525 | +or `-f 3`) whereas HTTP mode takes them via GET/POST data (e.g. `?foo=1`).
|
| 526 | +(Note that per long-standing fossil convention CLI parameters taking a
|
| 527 | +value do not use an equal sign before the value!)
|
| 528 | +
|
| 529 | +For example:
|
| 530 | +
|
| 531 | +- HTTP: `/json/timeline/wiki?after=2011-09-01&limit=3`
|
| 532 | +- CLI: `fossil json timeline wiki --after 2011-09-01 --limit 3`
|
| 533 | +
|
| 534 | +Some commands may only work in one mode or the other (for various
|
| 535 | +reasons). In CLI mode the user automatically has full setup/admin
|
| 536 | +access.
|
| 537 | +
|
| 538 | +In HTTP mode, request-specific options can also be specified in the
|
| 539 | +`POST.payload` data, and doing so actually has an advantage over
|
| 540 | +specifying them as URL parameters: posting JSON data retains the full
|
| 541 | +type information of the values, whereas GET-style parameters are always
|
| 542 | +strings and must be explicitly type-checked/converted (which may produce
|
| 543 | +unpredictable results when given invalid input). That said, oftentimes
|
| 544 | +it is more convenient to pass the options via URL parameters, rather
|
| 545 | +than generate the request envelope and payload required by POST
|
| 546 | +requests, and the JSON API makes some extra effort to treat GET-style
|
| 547 | +parameters type-equivalent to their POST counterparts. If a property
|
| 548 | +appears in both GET and `POST.payload`, GET-style parameters *typically*
|
| 549 | +take precedence over `POST.payload` by long-standing convention (=="PHP
|
| 550 | +does it this way by default").
|
| 551 | +
|
| 552 | +(That is, however, subject to eventual reversal because of the
|
| 553 | +stronger type safety provided by POSTed JSON. Philosophically
|
| 554 | +speaking, though, GET *should* take precedence, in the same way that
|
| 555 | +CLI-provided options conventionally override app-configuration-level
|
| 556 | +options.)
|
| 557 | +
|
| 558 | +One notable functional difference between CLI and HTTP modes is that in
|
| 559 | +CLI mode error responses *might* be accompanied by a non-0 exit status
|
| 560 | +(they "should" always be, but there might be cases where that does not
|
| 561 | +yet happen) whereas in HTTP mode we always try to exit with code 0 to
|
| 562 | +avoid generating an HTTP 500 ("internal server error"), which could keep
|
| 563 | +the JSON response from being delivered. The JSON code only intentionally
|
| 564 | +allows an HTTP 500 when there is a serious internal error like
|
| 565 | +allocation or assertion failure. HTTP clients are expected to catch
|
| 566 | +errors by evaluating the response object, not the HTTP result code.
|
| 567 | +
|
| 568 | +<a id="simulating-post-data"></a>
|
| 569 | +# Simulating POSTed data
|
| 570 | +
|
| 571 | +We have a mechanism to feed request data to CLI mode via
|
| 572 | +files (simulating POSTed data), as demonstrated in this example:
|
| 573 | +
|
| 574 | +```console
|
| 575 | +$ cat in.json
|
| 576 | +{ "command": "timeline/wiki", "indent":2, "payload":{"limit":1}}
|
| 577 | +$ fossil json --json-input in.json # use filename - for stdin
|
| 578 | +```
|
| 579 | +
|
| 580 | +The above is equivalent to:
|
| 581 | +
|
| 582 | +```console
|
| 583 | +$ echo '{"indent":2, "payload":{"limit":1}}' \
|
| 584 | + | fossil json timeline wiki --json-input -
|
| 585 | +```
|
| 586 | +
|
| 587 | +Note that the "command" JSON parameter is only checked when no json
|
| 588 | +subcommand is provided on the CLI or via the HTTP request path. Thus we
|
| 589 | +cannot pass the CLI args "json timeline" in conjunction with a "command"
|
| 590 | +string of "wiki" this way.
|
| 591 | +
|
| 592 | +***HOWEVER...***
|
| 593 | +
|
| 594 | +Much of the existing JSON code was written before the `--json-input`
|
| 595 | +option was possible. Because of this, there might be some
|
| 596 | +"misinteractions" when providing request-specific options via *both*
|
| 597 | +CLI options and simulated POST data. Those cases will eventually be
|
| 598 | +ironed out (with CLI options taking "POSTing" data in CLI edble results always
|
| 599 | +provide any options via the JSON request data, not CLI arguments. That
|
| 600 | +said, there "should not" be any blatant incompatibilities, but some
|
| 601 | +routines will prefer `POST.payload` over CLI/GET arguments, so there
|
| 602 | +are some minor inconsistencies across various commands with regards to
|
| 603 | +which source (POST/GET/CLI |
|
| 604 | +| onses,
|
| 605 | + only for succes |
|
| 606 | +| | |
|
| 607 | +| | This option is particularly |
|
| 608 | +| |responses (and only those which a |
|
| 609 | +| | piping in to CLI mode, but it |
|
| 610 | +| | also has some |
|
| 611 | +| p (GMT Unix Epoch). We use seconds |
|
| 612 | +| | client side. |
|
| 613 | ++-----------------------------------+-----------------------------------+
|
| 614 | +| authTokee
|
| 615 | +
|
| 616 | +Every response comes in the for |
|
| 617 | +| e comes in the form of an HTTP response or (in CLI mode)
|
| 618 | +JSON sent to stdout. The body of the response is a JSON object following
|
| 619 | +a common envelope format. The envelope has the following properties:
|
| 620 | +
|
| 621 | +
|
| 622 | +- `fossil`: Fossil server version string. This property is basically
|
| 623 | + "the official response envelope marker" - if it is using tained it, and then it is
|
| 624 | + echoed back to the caller as-is. This can be used to determine
|
| 625 | + (client-side) which request a given response is coming in for
|
| 626 | + (assuming multiple asynchronous requests are pending). In practice
|
| 627 | + this generally isn’t needed because response handling tends to be
|
| 628 | + done by closures associated with the original request object (at
|
| 629 | + least in JavaScript code). In languages without closures it might
|
| 630 | + have some use. It may be any legal JSON value - it need not be
|
| 631 | + confined to a string or number.
|
| 632 | +- `resultCode`: Standardized result code string in the form
|
| 633 | + `FOSSIL-####`. Only error responses contain a `resultCode`.
|
| 634 | +- `resultText`: Possibly a descriptive string, possibly
|
| 635 | + empty. Supplements the resultCode, but can also be set on success
|
| 636 | + responses (but normally isn't). Clients must not rely on any
|
| 637 | + specific values being set here.
|
| 638 | +- `payload`: Request-specific response payload (data type/structure is
|
| 639 | + request-specific). The payload is never set for error responses,
|
| 640 | + only for success responses (and only those which actually have a
|
| 641 | + payload - not all do).
|
| 642 | +- `timestamp`: Response timestamp (GMT Unix Epoch). We use seconds
|
| 643 | + precision because I did not know at the time that Fossil actually
|
| 644 | + records millisecond precision.
|
| 645 | +- `payloadVersion`: Not initially needed, but reserved for future use
|
| 646 | + in maintaining version compatibility when the format of a given
|
| 647 | + response type's payload changes. If needed, the "first version"
|
| 648 | + value is assumed to be 0, for semantic [near-]compatibility with the
|
| 649 | + undefined value clients see when this property is not set.
|
| 650 | +- `command`: Normalized form of the command being run. It consists of
|
| 651 | + the "command" (non-argument) parts of the request path (or CLI
|
| 652 | + positional arguments), excluding the initial "/json/" part. e.g. the
|
| 653 | + "command" part of "/json/timeline/checkin?a=b" (CLI: json timeline
|
| 654 | + checkin...) is "timeline/checkin" (both in CLI and HTTP modes).
|
| 655 | +- `apiVersion`: Not yet used, but reserved for a numeric value which
|
| 656 | + represents the JSON API's version (which can be used to determine if
|
| 657 | + it has a given feature or not). This will not be implemented until
|
| 658 | + it's needed.
|
| 659 | +- `warnings`: Reserved for future use as a standard place to put
|
| 660 | + non-fatal warnings in responses. Will be an array but the warning
|
| 661 | + structure/type is not yet specified. Intended primarily as a
|
| 662 | + debugging tool, and will "probably not" become part of the public
|
| 663 | + client interface.
|
| 664 | +- `g`: Fossil administrators (those with the "a" or "s" permissions)
|
| 665 | + may set the `debugFossilG` boolean request parameter (CLI:
|
| 666 | + `--json-debug-g`) to enable this property for any given response. It
|
| 667 | + contains a good deal of the server-side internal state at the time
|
| 668 | + the response was generated, which is often useful in debuggering
|
| 669 | + problems. Trivia: it is called "g" because that's the name of
|
| 670 | + fossil's internal global state object.
|
| 671 | +- `procTimeMs`: For debugging only - generic clients must not rely on
|
| 672 | + this property. Contains the number of milliseconds the JSON command
|
| 673 | + processor needed to dispatch and process the command. TODO: move the
|
| 674 | + timer into the fossil core so that we can generically time its
|
| 675 | + responses and include the startup overhead in the time calculation.
|
| 676 | +
|
| 677 | +
|
| 678 | +
|
| 679 | +<a id="http-response-header"></a>
|
| 680 | +# HTTP Response Headers
|
| 681 | +
|
| 682 | +The Content-Type HTTP header of a response will be either
|
| 683 | +application/json, application/javascript, or text/plain, depending on
|
| 684 | +whether or not we are in JSONP mode or (failing that) the contents of
|
| 685 | +the "Accept" header sent in the request. The response type will be
|
| 686 | +text/plain if it cannot figure out what to do. The response's
|
| 687 | +Content-Type header *may* contain additional metadata, e.g. it might
|
| 688 | +look like: application/json; charset=utf-8
|
| 689 | +
|
| 690 | +Apropos UTF-8: note that JSON is, by definition, Unicode and recommends
|
| 691 | +UTF-8 encoding (which is what we use). That means if your console cannot
|
| 692 | +handle UTF-8 then using this API in CLI mode might (depending on the
|
| 693 | +content) render garbage on your screen.
|
| 694 | +
|
| 695 | +
|
| 696 | +<a id="cli-vs-http"></a>
|
| 697 | +# CLI vs. HTTP Mode
|
| 698 | +
|
| 699 | +CLI (command-line interface) and HTTP modes (CGI and standalone server)
|
| 700 | +are consolidated in the same implementations and behave essentially
|
| 701 | +identically, with only minor exceptions.
|
| 702 | +
|
| 703 | +An HTTP path of `/json/foo` translates to the CLI command `fossil json
|
| 704 | +foo`. CLI mode takes options in the fossil-convention forms (e.g. `--foo 3`
|
| 705 | +or `-f 3`) whereas HTTP mode takes them via GET/POST data (e.g. `?foo=1`).
|
| 706 | +(Note that per long-standing fossil convention CLI parameters taking a
|
| 707 | +value do not use an equal sign before the value!)
|
| 708 | +
|
| 709 | +For example:
|
| 710 | +
|
| 711 | +- HTTP: `/json/timeline/wiki?after=2011-09-01&limit=3`
|
| 712 | +- CLI: `fossil json timeline wiki --after 2011-09-01 --limit 3`
|
| 713 | +
|
| 714 | +Some commands may only work in one mode or the other (for various
|
| 715 | +reasons). In CLI mode the user automatically has full setup/admin
|
| 716 | +access.
|
| 717 | +
|
| 718 | +In HTTP mode, request-specific options can also be specified in the
|
| 719 | +`POST.payload` data, and doing so actually has an advantage over
|
| 720 | +specifying them as URL parameters: posting JSON data retains the full
|
| 721 | +type information of the values, whereas GET-style parameters are always
|
| 722 | +strings and must be explicitly type-checked/converted (which may produce
|
| 723 | +unpredictable results when given invalid input). That said, oftentimes
|
| 724 | +it is more convenient to pass the options via URL parameters, rather
|
| 725 | +than generate the request envelope and payload required by POST
|
| 726 | +requests, and the JSON API makes some extra effort to treat GET-style
|
| 727 | +parameters type-equivalent to their POST counterparts. If a property
|
| 728 | +appears in both GET and `POST.payload`, GET-style parameters *typically*
|
| 729 | +take precedence over `POST.payload` by long-standing convention (=="PHP
|
| 730 | +does it this way by default").
|
| 731 | +
|
| 732 | +(That is, however, subject to eventual reversal because of the
|
| 733 | +stronger type safety provided by POSTed JSON. Philosophically
|
| 734 | +speaking, though, GET *should* take precedence, in the same way that
|
| 735 | +CLI-provided options conventionally override app-configuration-level
|
| 736 | +options.)
|
| 737 | +
|
| 738 | +One notable functional difference between CLI and HTTP modes is that in
|
| 739 | +CLI mode error responses *might* be accompanied by a non-0 exit status
|
| 740 | +(they "should" always be, but there might be cases where that does not
|
| 741 | +yet happen) whereas in HTTP mode we always try to exit with code 0 to
|
| 742 | +avoid generating an HTTP 500 ("internal server error"), which could keep
|
| 743 | +the JSON response from being delivered. The JSON code only intentionally
|
| 744 | +allows an HTTP 500 when there is a serious internal error like
|
| 745 | +allocation or assertion failure. HTTP clients are expected to catch
|
| 746 | +errors by evaluating the response object, not the HTTP result code.
|
| 747 | +
|
| 748 | +<a id="simulating-post-data"></a>
|
| 749 | +# Simulating POSTed data
|
| 750 | +
|
| 751 | +We have a mechanism to feed request data to CLI mode via
|
| 752 | +files (simulating POSTed data), as demonstrated in this example:
|
| 753 | +
|
| 754 | +```console
|
| 755 | +$ cat in.json
|
| 756 | +{ "command": "timeline/wiki", "indent":2, "payload":{"limit":1}}
|
| 757 | +$ fossil json --json-input in.json # use filename - for stdin
|
| 758 | +```
|
| 759 | +
|
| 760 | +The above is equivalent to:
|
| 761 | +
|
| 762 | +```console
|
| 763 | +$ echo '{"indent":2, "payload":{"limit":1}}' \
|
| 764 | + | fossil json timeline wiki --json-input -
|
| 765 | +```
|
| 766 | +
|
| 767 | +Note that the "command" JSON parameter is only checked when no json
|
| 768 | +subcommand is provided on the CLI or via the HTTP request path. Thus we
|
| 769 | +cannot pass the CLI args "json timeline" in conjunction with a "command"
|
| 770 | +string of "wiki" this way.
|
| 771 | +
|
| 772 | +***HOWEVER...***
|
| 773 | +
|
| 774 | +Much of the existing JSON code was written before the `--json-input`
|
| 775 | +option was possible. Because of this, there might be some
|
| 776 | +"misinteractions" when providing request-specific options via *both*
|
| 777 | +CLI options and simulated POST data. Those cases will eventually be
|
| 778 | +ironed out (with CLI options taking "POSTing" data in CLI edble results always
|
| 779 | +provide any options via the JSON request data, not CLI arguments. That
|
| 780 | +said, there "should not" be any blatant incompatibilities, but some
|
| 781 | +routines will prefer `POST.payload` over CLI/GET arguments, so there
|
| 782 | +are some minor inconsistencies across various commands with regards to
|
| 783 | +which source (POST/GET/CLI) takes precedence for a given option. The
|
| 784 | +precedence "should always be the same," but currently cannot be due to
|
| 785 | +core fossil implementation details (the internal consolidation of
|
| 786 | +GET/CLI/POST vars into a single set).
|
| 787 | +
|
| 788 | +
|
| 789 | +<a id="json-indentation"></a>
|
| 790 | +# Indentation/Formatting of JSON Output
|
| 791 | +
|
| 792 | +CLI mode accepts the `--indent|-I #` option to set the indention level
|
| 793 | +and HTTP mode accepts `indent=#` as a GET/POST parameter. The semantics
|
| 794 | +of the indention level are derived from the underlying JSON library and
|
| 795 | +have the following meanings: 0 (zero) or less disables all superfluous
|
| 796 | +indentation (this is the default in HTTP mode). A value of 1 uses 1 hard
|
| 797 | +TAB character (ASCII 0x09) per level of indention (the default in CLI
|
| 798 | +mode). Values greater than 1 use that many whitespaces (ASCII 32d) per
|
| 799 | +level of indention. e.g. a value of 7 uses 7 spaces per level of
|
| 800 | +indention. There is no way to specify one whitespace per level, but if
|
| 801 | +you *really* want one whitespace instead of one tab (same data size) you
|
| 802 | +can filter the output to globally replace ASCII 9dec (TAB) with ASCII
|
| 803 | +32dec (space). Because JSON string values *never* contain hard tabs
|
| 804 | +(they are represented by `\t`) there is no chance that such a global
|
| 805 | +replacement will corrupt JSON string contents - only the formatting will
|
| 806 | +be affected.
|
| 807 | +
|
| 808 | +Potential TODO: because extraneous indention "could potentially" be used
|
| 809 | +as a form of DoS, the option *might* be subject to later removal from HTTP
|
| 810 | +mode (in CLI it's fine).
|
| 811 | +
|
| 812 | +In HTTP mode no trailing newline is added to the output, whereas in CLI
|
| 813 | +mode one is normally appended (exception: in JSONP mode no newline is
|
| 814 | +appended, tisuccess responses contain no i little reason to implement this, since assertions are "truly
|
| 815 | + serious" errors.
|
| 816 | +- `FOSSIL-1107`: Allocation/out of memory error. This cannot be reasonably
|
| 817 | + reported because fossil aborts if an allocation fails.
|
| 818 | +- `FOSSIL-1108`: Requested API is not yet implemented.
|
| 819 | +- `FOSSIL-1109`: Panic! Fossil's `fossil_panic()` or `cgi_panic()` was
|
| 820 | + called. In non-JSON HTML mode this produces an HTTP 500
|
| 821 | + error. Clients "should" report this as a potential bug, as it
|
| 822 | + "possibly" indicates that the C code has incorrect argument- or
|
| 823 | + error handling somewhere.
|
| 824 | +- `FOSSIL-1110`: Reading of artifact manifest failed. Time to contact
|
| 825 | + your local fossil guru.
|
| 826 | +- `FOSSIL-1111`: Opening of file failed (e.g. POST data provided to
|
| 827 | + CLI mode).
|
| 828 | +
|
| 829 | +
|
| 830 | +**`FOSSIL-2000`: Authentication/Access Error Category**
|
| 831 | +
|
| 832 | +- `FOSSIL-2001`: Privileged request was missing authentication
|
| 833 | + token/cookie.
|
| 834 | +- `FOSSIL-2002`: Access to requested resource was denied. Oftentimes
|
| 835 | + the `resultText` property will contain a human-language description of
|
| 836 | + the access rights needed for the given command.
|
| 837 | +- `FOSSIL-2003`: Requested command is not available in the current
|
| 838 | + operating mode. Returned in CLI mode by commands which require HTTP
|
| 839 | + mode (e.g. login), and vice versa. FIXME: now that we can simulate
|
| 840 | + POST in CLI mode, we can get rid of this distincuse the debugFossilG Login Failed.
|
| 841 | +- `FOSSIL-2101`: Ano--json-debug-g-2101`: Anonymous login attempt is missing the
|
| 842 | + "anonymousSeed" property (fetched via [the `/json/anonymousPassword`
|
| 843 | + request](api-auth.md#login-anonymous)). Note that this is more
|
| 844 | + specific form of `FOSSIL-3002`.
|
| 845 | +
|
| 846 | +
|
| 847 | +ONLY FOR TESTING purposes should the remaning 210X sub-codes be
|
| 848 | +enabled (they are potentially security-relevant, in that the client
|
| 849 | +knows which part of the request was valid/invalid):
|
| 850 | +
|
| 851 | +- `FOSSIL-2102`: Name not supplied in login request
|
| 852 | +- `FOSSIL-2103`: Password not supplied in login request
|
| 853 | +- `FOSSIL-2104`: No name/password match found
|
| 854 | +
|
| 855 | +
|
| 856 | +**`FOSSIL-3000`: Usage Error Category**
|
| 857 | +
|
| 858 | +- `FOSSIL-3001`: Invalid argument/parameter type(s) or value(s) in
|
| 859 | + request
|
| 860 | +- `FOSSIL-3002`: Required argument(s)/parameter(s) missing from
|
| 861 | + request
|
| 862 | +- `FOSSIL-3003`: Requested resource identifier is ambiguous (e.g. a
|
| 863 | + shortened hash that matches multiple artifacts, an abbreviated
|
| 864 | + date that matches multiple commits, etc.)
|
| 865 | +- `FOSSIL-3004`: Unresolved resource identifier. A branch/tag/uuid
|
| 866 | + provided by client code could not be resolved. This is a special
|
| 867 | + case of #3006.
|
| 868 | +- `FOSSIL-3005`: Resource already exists and overwriting/replacing is
|
| 869 | + not allowed. e.g. trying to create a wiki page or user which already
|
| 870 | + exists. FIXME? Consolidate this and resource-not-found into a
|
| 871 | + separate category for dumb-down purposes?
|
| 872 | +- `FOSSIL-3006`: Requested resource not found. e.g artifact ID, branch
|
| 873 | + name, etc.
|
| 874 | +
|
| 875 | +
|
| 876 | +**`FOSSIL-4000`: Database-related Error Category**
|
| 877 | +
|
| 878 | +- `FOSSIL-4001`: Statement preparation failed.
|
| 879 | +- `FOSSIL-4002`: Parameter binding failed.
|
| 880 | +- `FOSSIL-4003`: Statement execution failed.
|
| 881 | +- `FOSSIL-4004`: Database locked (this is not used anywhere, but
|
| 882 | + reserved for future use).
|
| 883 | +
|
| 884 | +Special-case DB-related errors...
|
| 885 | +
|
| 886 | +- `FOSSIL-4101`: Fossil Schema out of date (repo rebuild required).
|
| 887 | +- `FOSSIL-4102`: Fossil repo db could not be found.
|
| 888 | +- `FOSSIL-4103`: Repository db is not valid (possibly corrupt).
|
| 889 | +- `FOSSIL-4104`: Check-out not found. This is similar to FOSSIL-4102
|
| 890 | + but indicates that a local checkout is required (but was not
|
| 891 | + found). Note that the 4102 gets triggered earlier than this one, and
|
| 892 | + so can appear in cases when a user might otherwise expect a 4104
|
| 893 | + error.
|
| 894 | +
|
| 895 | +
|
| 896 | +Some of those error codes are of course "too detailed" for the client to
|
| 897 | +do anything with (e.g.. 4001-4004), but their intention is to make it
|
| 898 | +easier for Fossil developers to (A) track down problems and (B) support
|
| 899 | +clients who report problems. If a client reports, "I get a FOSSIL-4000,
|
| 900 | +how can I fix it?" then the developers/support personnel can't say much
|
| 901 | +unless they know if it's a 4001, 4002, 4003, 4004, or 4101 (in which
|
| 902 | +case they can probably zero in on the problem fairly quickly, since they
|
| 903 | +know which API call triggered it and they know (from the error code) the
|
| 904 | +general source of the problem).
|
| 905 | +
|
| 906 | +## Why Standard/Immutable Result Codes are Important
|
| 907 | +
|
| 908 | +- They are easily internationalized (i.e. associated with non-English
|
| 909 | + error text)
|
| 910 | +- Clients may be able to add automatic retry strategies for certain
|
| 911 | + problem types by examining the result code. e.g. if fossil returns a
|
| 912 | + locking or timeout error \[it currently does no special
|
| 913 | + timeout/locking handling, by the way\] the client could re-try,
|
| 914 | + whereas a usage error cannot be sensibly retried with the same
|
| 915 | + inputs.
|
| 916 | +- The "category" structure described above allows us some degree of
|
| 917 | + flexibility in how detailed the reported errors are reported.
|
| 918 | +- While the string prefix "FOSSIL-" on the error codes may seem
|
| 919 | + superfluous, it has one minor *potential* advantage on the client
|
| 920 | + side: when managing several unrelated data sources, these error
|
| 921 | + codes can be immediately identified (by higher-level code which may
|
| 922 | + be ignorant of the data source) as having comUUID can be ambiguous).the form
|
| 923 | + `FOSSIL-####`. Only error responses contain a `resultCode`.
|
| 924 | +- `resultText`: Possibly a descriptive string, possibly
|
| 925 | + empty. Supplements the resultCode, but can also be set on success
|
| 926 | + responses (but normally isn't). Clients must not rely on any
|
| 927 | + specific values being set here.
|
| 928 | +- `payload`: Request-specific response payload (data type/structure is
|
| 929 | + request-specific). The payload is never set for error responses,
|
| 930 | + only for success responses (and only those which actually have a
|
| 931 | + payload - not all do).
|
| 932 | +- `timestamp`: Response timestamp (GMT Unix Epoch). We use seconds
|
| 933 | + precision because ivelope
|
| 934 | +
|
| 935 | +Every response comes in the form of an HTTP response or (in CLI mode)
|
| 936 | +JSON sent to stdout. The body of the response is a JSON object following
|
| 937 | +a common envelope format. The envelope has the following properties:
|
| 938 | +
|
| 939 | +
|
| 940 | +- `fossil`: Fossil server version string. This property is basically
|
| 941 | + "the official response envelope marker" - if it is set, clients can
|
| 942 | + "probably safely assume" that the object indeed came from one of the
|
| 943 | + Fossil/JSON APIs. This API never creates responses which do not
|
| 944 | + contain this property.
|
| 945 | +- `requestId`: Only ple asynchronous requ
|
| 946 | +sts are pending). In practice
|
| 947 | + this generally isn’t needed because response handling tends to be
|
| 948 | + done by closures associated with the original request object (at
|
| 949 | + least in JavaScript code). In languages without closures it might
|
| 950 | + have some use. It may be any legal JSON value - it need not be
|
| 951 | + confined to a string or number.
|
| 952 | +- `resultCode`: Standardized result code string in the form
|
| 953 | + `FOSSIL-####`. Only error responses contain a `resultCode`.
|
| 954 | +- `resultText`: Possibly a descriptive string, possibly
|
| 955 | + empty. Supplements the resultCode, but can also be set on success
|
| 956 | + responses (but normally isn't). Clients must not rely on any
|
| 957 | + specific values being set here.
|
| 958 | +- `payload`: Request-specific response payload (data type/structure is
|
| 959 | + request-specific). The payload is never set for error responses,
|
| 960 | + only for success responses (and only those which actually have a
|
| 961 | + payload - not all do).
|
| 962 | +- `timestamp`: Respons |