|
1
|
# JSON API: /settings |
|
2
|
([⬑JSON API Index](index.md)) |
|
3
|
|
|
4
|
Jump to: |
|
5
|
|
|
6
|
* [Fetch Settings](#get) |
|
7
|
* [Set Settings](#set) |
|
8
|
|
|
9
|
--- |
|
10
|
|
|
11
|
<a id="get"></a> |
|
12
|
# Fetch Settings |
|
13
|
|
|
14
|
**Status:** Implemented 20230120 |
|
15
|
|
|
16
|
**Required permissions:** "o" |
|
17
|
|
|
18
|
**Request:** `/json/settings/get[?version=X]` |
|
19
|
|
|
20
|
**Response payload example:** |
|
21
|
|
|
22
|
```json |
|
23
|
{ |
|
24
|
"access-log":{ |
|
25
|
"versionable":false, |
|
26
|
"sensitive":false, |
|
27
|
"defaultValue":"off", |
|
28
|
"valueSource":null, |
|
29
|
"value":null |
|
30
|
}, |
|
31
|
... |
|
32
|
"binary-glob":{ |
|
33
|
"versionable":true, |
|
34
|
"sensitive":false, |
|
35
|
"defaultValue":null, |
|
36
|
"valueSource":"versioned", |
|
37
|
"value":"*.gif\n*.ico\n*.jpg\n*.odp\n*.dia\n*.pdf\n*.png\n*.wav..." |
|
38
|
}, |
|
39
|
... |
|
40
|
"web-browser":{ |
|
41
|
"versionable":false, |
|
42
|
"sensitive":true, |
|
43
|
"defaultValue":null, |
|
44
|
"valueSource":"repo", |
|
45
|
"value":"firefox" |
|
46
|
} |
|
47
|
} |
|
48
|
``` |
|
49
|
|
|
50
|
Each key in the payload is the name of a fossil-recognized setting, |
|
51
|
modeled as an object. The keys of that are: |
|
52
|
|
|
53
|
|
|
54
|
- `defaultValue`: the setting's default value, or `null` if no default |
|
55
|
is defined. |
|
56
|
- `value`: The current value of that setting. |
|
57
|
- `valueSource`: one of (`"repo"`, `"checkout"`, `"versioned"`, or |
|
58
|
`null`), specifying the data source where the setting was found. The |
|
59
|
settings sources are checked in this order and the first one found |
|
60
|
is the result: |
|
61
|
- If `version=X` is provided, check-in `X` is searched for a |
|
62
|
versionable-settings file. If found, its value is used and |
|
63
|
`valueSource` will be `"versioned"`. If `X` is not a checkin, an |
|
64
|
error response is produced with code `FOSSIL-3006`. |
|
65
|
- If a versionable setting is found in the current checkout, its |
|
66
|
value is used and `valueSource` will be `"versioned"` |
|
67
|
- If the setting is found in checkout database's `vvar` table, its |
|
68
|
value is used and `valueSource` will be `"checkout"`. |
|
69
|
- If the setting is found in repository's `config` table, its |
|
70
|
value is used and `valueSource` will be `"repo"`. |
|
71
|
- If no value is found, `null` is used for both the `value` and |
|
72
|
`valueSource` results. Note that _global settings are never |
|
73
|
checked_ because they can leak information which have nothing |
|
74
|
specifically to do with the given repository. |
|
75
|
- `sensitive`: a value which fossil has flagged as sensitive can only |
|
76
|
be fetched by a Setup user. For other users, they will always have |
|
77
|
a `value` and `valueSource` of `null`. |
|
78
|
- `versionable`: `true` if the setting is tagged as versionable, else |
|
79
|
`false`. |
|
80
|
|
|
81
|
Note that settings are internally stored as strings, even if they're |
|
82
|
semantically treated as numbers. The way settings are stored and |
|
83
|
handled does not give us enough information to recognize their exact |
|
84
|
data type here so they are passed on as-is. |
|
85
|
|
|
86
|
|
|
87
|
<a id="set"></a> |
|
88
|
# Set Settings |
|
89
|
|
|
90
|
**Status:** Implemented 20230120 |
|
91
|
|
|
92
|
**Required permissions:** "s" |
|
93
|
|
|
94
|
**Request:** `/json/settings/set` |
|
95
|
|
|
96
|
This call requires that the input payload be an object containing a |
|
97
|
mapping of fossil-known configuration keys (case-sensitive) to |
|
98
|
values. For example: |
|
99
|
|
|
100
|
```json |
|
101
|
{ |
|
102
|
"editor": "emacs", |
|
103
|
"admin-log": true, |
|
104
|
"auto-captcha": false |
|
105
|
} |
|
106
|
``` |
|
107
|
|
|
108
|
It iterates through each property, which must have a data type of |
|
109
|
`null`, boolean, number, or string. A value of `null` _unsets_ |
|
110
|
(deletes) the setting. Boolean values are stored as integer 0 |
|
111
|
or 1. All other types are stored as-is. It only updates the |
|
112
|
`repository.config` database and never updates a checkout or global |
|
113
|
config database, nor is it capable of updating versioned settings |
|
114
|
(^Updating versioned settings requires creating a full check-in.). |
|
115
|
|
|
116
|
It has no result payload but this may be changed in the future it |
|
117
|
practice shows that it should return something specific. |
|
118
|
|
|
119
|
Error responses include: |
|
120
|
|
|
121
|
- `FOSSIL-2002`: called without "setup" permissions. |
|
122
|
- `FOSSIL-3002`: called without a payload object. |
|
123
|
- `FOSSIL-3001`: passed an unknown config option. |
|
124
|
- `FOSSIL-3000`: a value has an unsupported data type. |
|
125
|
|
|
126
|
If an error is triggered, any settings made by this call up until that |
|
127
|
point are discarded. |
|
128
|
|