gemstash 2.8.1 → 2.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. checksums.yaml +4 -4
  2. data/lib/gemstash/authorization.rb +0 -2
  3. data/lib/gemstash/cache.rb +5 -4
  4. data/lib/gemstash/cli/base.rb +9 -2
  5. data/lib/gemstash/cli/setup.rb +1 -1
  6. data/lib/gemstash/cli/start.rb +4 -0
  7. data/lib/gemstash/configuration.rb +71 -1
  8. data/lib/gemstash/db/upstream.rb +30 -2
  9. data/lib/gemstash/dependencies.rb +28 -5
  10. data/lib/gemstash/env.rb +4 -2
  11. data/lib/gemstash/gem_fetcher.rb +1 -2
  12. data/lib/gemstash/gem_pusher.rb +24 -20
  13. data/lib/gemstash/gem_source/private_source.rb +22 -6
  14. data/lib/gemstash/gem_source/upstream_source.rb +129 -34
  15. data/lib/gemstash/http_client.rb +167 -8
  16. data/lib/gemstash/logging.rb +3 -1
  17. data/lib/gemstash/man/gemstash-authorize.1 +29 -48
  18. data/lib/gemstash/man/gemstash-authorize.1.txt +14 -14
  19. data/lib/gemstash/man/gemstash-configuration.5 +231 -154
  20. data/lib/gemstash/man/gemstash-configuration.5.txt +208 -93
  21. data/lib/gemstash/man/gemstash-customize.7 +150 -168
  22. data/lib/gemstash/man/gemstash-customize.7.txt +80 -86
  23. data/lib/gemstash/man/gemstash-debugging.7 +20 -33
  24. data/lib/gemstash/man/gemstash-debugging.7.txt +5 -7
  25. data/lib/gemstash/man/gemstash-deploy.7 +31 -53
  26. data/lib/gemstash/man/gemstash-deploy.7.txt +17 -18
  27. data/lib/gemstash/man/gemstash-mirror.7 +24 -37
  28. data/lib/gemstash/man/gemstash-mirror.7.txt +14 -9
  29. data/lib/gemstash/man/gemstash-multiple-sources.7 +105 -110
  30. data/lib/gemstash/man/gemstash-multiple-sources.7.txt +62 -41
  31. data/lib/gemstash/man/gemstash-private-gems.7 +87 -136
  32. data/lib/gemstash/man/gemstash-private-gems.7.txt +30 -30
  33. data/lib/gemstash/man/gemstash-readme.7 +105 -127
  34. data/lib/gemstash/man/gemstash-readme.7.txt +43 -49
  35. data/lib/gemstash/man/gemstash-setup.1 +22 -42
  36. data/lib/gemstash/man/gemstash-setup.1.txt +12 -12
  37. data/lib/gemstash/man/gemstash-start.1 +9 -27
  38. data/lib/gemstash/man/gemstash-start.1.txt +5 -5
  39. data/lib/gemstash/man/gemstash-status.1 +9 -27
  40. data/lib/gemstash/man/gemstash-status.1.txt +5 -5
  41. data/lib/gemstash/man/gemstash-stop.1 +9 -27
  42. data/lib/gemstash/man/gemstash-stop.1.txt +5 -5
  43. data/lib/gemstash/man/gemstash-version.1 +8 -28
  44. data/lib/gemstash/man/gemstash-version.1.txt +2 -2
  45. data/lib/gemstash/puma.rb +1 -0
  46. data/lib/gemstash/rack_env_rewriter.rb +3 -0
  47. data/lib/gemstash/upstream.rb +83 -6
  48. data/lib/gemstash/version.rb +1 -1
  49. data/lib/gemstash/web.rb +12 -0
  50. metadata +7 -7
@@ -1,18 +1,18 @@
1
- 4mgemstash-authorize24m(1) 4mgemstash-authorize24m(1)
1
+ 4mgemstash-authorize24m(1) General Commands Manual 4mgemstash-authorize24m(1)
2
2
 
3
3
  1mName0m
4
4
  gemstash-authorize - Adds or removes authorization to interact with
5
5
  privately stored gems
6
6
 
7
7
  1mSynopsis0m
8
- 1mgemstash authorize [permissions] [--remove] [--list] [--key SECURE_KEY]0m
9
- 1m[--name NAME] [--config-file FILE]0m
8
+ gemstash authorize [permissions] [--remove] [--list] [--key SECURE_KEY]
9
+ [--name NAME] [--config-file FILE]
10
10
 
11
11
  1mDescription0m
12
12
  Adds or removes authorization to interact with privately stored gems.
13
13
 
14
14
  Any arguments will be used as specific permissions. Valid permissions
15
- include 1mpush22m, 1myank22m, and 1mfetch22m. If no permissions are provided, then
15
+ include push, yank, and fetch. If no permissions are provided, then
16
16
  all permissions will be granted (including any that may be added in fu-
17
17
  ture versions of Gemstash).
18
18
 
@@ -25,26 +25,26 @@
25
25
  gemstash authorize --list
26
26
 
27
27
  1mOptions0m
28
- o 1m--config-file FILE22m: Specify the config file to use. If you aren't
29
- using the default config file at 1m~/.gemstash/config.yml 22mor 1m~/.gem-0m
30
- 1mstash/config.yml.erb22m, then you must specify the config file via this
28
+ o --config-file FILE: Specify the config file to use. If you aren't
29
+ using the default config file at ~/.gemstash/config.yml or ~/.gem-
30
+ stash/config.yml.erb, then you must specify the config file via this
31
31
  option.
32
32
 
33
- o 1m--key SECURE_KEY22m: Specify the API key to affect. This should be the
33
+ o --key SECURE_KEY: Specify the API key to affect. This should be the
34
34
  actual key value, not a name. This option is required when using
35
- 1m--remove 22mbut is optional otherwise. If adding an authorization, us-
35
+ --remove but is optional otherwise. If adding an authorization, us-
36
36
  ing this will either create or update the permissions for the speci-
37
37
  fied API key. If missing, a new API key will always be generated.
38
38
  Note that a key can only have a maximum length of 255 chars.
39
39
 
40
- o 1m--name22m: Name of the authorization. Purely for ease of identifica-
40
+ o --name: Name of the authorization. Purely for ease of identifica-
41
41
  tion, not required.
42
42
 
43
- o 1m--remove22m: Remove an authorization rather than add or update one.
44
- When removing, permission values are not allowed. The 1m--key <secure-0m
45
- 1mkey> 22moption is required.
43
+ o --remove: Remove an authorization rather than add or update one.
44
+ When removing, permission values are not allowed. The --key <se-
45
+ cure-key> option is required.
46
46
 
47
- o 1m--list22m: List current authorizations. Provide 1m--name 22mor 1m--key 22mto show
47
+ o --list: List current authorizations. Provide --name or --key to show
48
48
  only one result.
49
49
 
50
50
  October 9, 2015 4mgemstash-authorize24m(1)
@@ -1,51 +1,38 @@
1
- .\" Automatically generated by Pandoc 3.1.3
1
+ .\" Automatically generated by Pandoc 3.7.0.2
2
2
  .\"
3
- .\" Define V font for inline verbatim, using C font in formats
4
- .\" that render this, and otherwise B font.
5
- .ie "\f[CB]x\f[]"x" \{\
6
- . ftr V B
7
- . ftr VI BI
8
- . ftr VB B
9
- . ftr VBI BI
10
- .\}
11
- .el \{\
12
- . ftr V CR
13
- . ftr VI CI
14
- . ftr VB CB
15
- . ftr VBI CBI
16
- .\}
17
- .TH "gemstash-configuration" "5" "October 13, 2015" "" ""
18
- .hy
3
+ .TH "gemstash\-configuration" "5" "October 13, 2015" ""
19
4
  .SH Name
20
- .PP
21
- gemstash-configuration
5
+ gemstash\-configuration
22
6
  .SH Synopsis
23
7
  .IP
24
- .nf
25
- \f[C]
26
- # \[ti]/.gemstash/config.yml
27
- ---
28
- :base_path: \[dq]/var/gemstash\[dq]
29
- :cache_type: memcached
30
- :memcached_servers: localhost:11211
31
- :db_adapter: postgres
32
- :db_url: postgres:///gemstash
33
- :db_connection_options:
34
- :test: true
35
- :pool_timeout: 2
36
- :rubygems_url: https://my.gem-source.local
37
- :ignore_gemfile_source: false
38
- :puma_threads: 32
39
- :bind: tcp://0.0.0.0:4242
40
- :protected_fetch: true
41
- :fetch_timeout: 10
42
- :open_timeout: 2
43
- :log_file: gemstash.log
44
- \f[R]
45
- .fi
8
+ .EX
9
+ \f[I]# \(ti/.gemstash/config.yml\f[R]
10
+ \-\-\-
11
+ :base_path\f[B]:\f[R] \(dq/var/gemstash\(dq
12
+ :cache_type\f[B]:\f[R] memcached
13
+ :memcached_servers\f[B]:\f[R] localhost:11211
14
+ :db_adapter\f[B]:\f[R] postgres
15
+ :db_url\f[B]:\f[R] postgres:///gemstash
16
+ :db_connection_options\f[B]:\f[R]
17
+ :test\f[B]:\f[R] true
18
+ :pool_timeout\f[B]:\f[R] 2
19
+ :rubygems_url\f[B]:\f[R] https://my.gem\-source.local
20
+ :ignore_gemfile_source\f[B]:\f[R] false
21
+ :allowed_upstreams\f[B]:\f[R]
22
+ \f[B]\-\f[R] https://my\-other.gem\-source.local
23
+ :allowed_redirects\f[B]:\f[R]
24
+ \f[B]\-\f[R] https://cdn.my\-other.gem\-source.local
25
+ :puma_threads\f[B]:\f[R] 32
26
+ :bind\f[B]:\f[R] tcp://0.0.0.0:4242
27
+ :protected_fetch\f[B]:\f[R] true
28
+ :fetch_timeout\f[B]:\f[R] 10
29
+ :max_upstream_duration\f[B]:\f[R] 300
30
+ :open_timeout\f[B]:\f[R] 2
31
+ :max_upstream_bytes\f[B]:\f[R] 67108864
32
+ :log_file\f[B]:\f[R] gemstash.log
33
+ .EE
46
34
  .SH Base Path
47
- .PP
48
- \f[V]:base_path\f[R]
35
+ \f[CR]:base_path\f[R]
49
36
  .PP
50
37
  Specifies where to store local files like the server log, cached gem
51
38
  files, and the database (when using SQLite).
@@ -53,136 +40,197 @@ If the default is being used, the directory will be created if it does
53
40
  not exist.
54
41
  Any other directory needs to be created ahead of time and be writable to
55
42
  the Gemstash server process.
56
- Specifying the \f[V]:base_path\f[R] via \f[V]gemstash setup\f[R] will
43
+ Specifying the \f[CR]:base_path\f[R] via \f[CR]gemstash setup\f[R] will
57
44
  create the directory for you.
58
45
  .SS Default value
59
- .PP
60
- \f[V]\[ti]/.gemstash\f[R]
46
+ \f[CR]\(ti/.gemstash\f[R]
61
47
  .SS Valid values
62
- .PP
63
48
  Any valid path
64
49
  .SH Cache Type
65
- .PP
66
- \f[V]:cache_type\f[R]
50
+ \f[CR]:cache_type\f[R]
67
51
  .PP
68
52
  Specifies how to cache values other than gem files (such as gem
69
53
  dependencies).
70
- \f[V]memory\f[R] will use an in memory cache while \f[V]memcached\f[R]
54
+ \f[CR]memory\f[R] will use an in memory cache while \f[CR]memcached\f[R]
71
55
  will point to 1 or more Memcached servers.
72
- Use the \f[V]:memcached_servers\f[R] configuration key for specifying
56
+ Use the \f[CR]:memcached_servers\f[R] configuration key for specifying
73
57
  where the Memcached server(s) are.
74
58
  .SS Default value
75
- .PP
76
- \f[V]memory\f[R]
59
+ \f[CR]memory\f[R]
77
60
  .SS Valid values
78
- .PP
79
- \f[V]memory\f[R], \f[V]memcached\f[R]
61
+ \f[CR]memory\f[R], \f[CR]memcached\f[R]
80
62
  .SH Memcached Servers
81
- .PP
82
- \f[V]:memcached_servers\f[R]
63
+ \f[CR]:memcached_servers\f[R]
83
64
  .PP
84
65
  Specifies the Memcached servers to connect to when using
85
- \f[V]memcached\f[R] for the \f[V]:cache_type\f[R].
86
- Only used when \f[V]memcached\f[R] is used for \f[V]:cache_type\f[R].
66
+ \f[CR]memcached\f[R] for the \f[CR]:cache_type\f[R].
67
+ Only used when \f[CR]memcached\f[R] is used for \f[CR]:cache_type\f[R].
87
68
  .SS Default value
88
- .PP
89
- \f[V]localhost:11211\f[R]
69
+ \f[CR]localhost:11211\f[R]
90
70
  .SS Valid values
91
- .PP
92
71
  A comma delimited list of Memcached servers
93
72
  .SH DB Adapter
94
- .PP
95
- \f[V]:db_adapter\f[R]
73
+ \f[CR]:db_adapter\f[R]
96
74
  .PP
97
75
  Specifies what database adapter to use.
98
- When \f[V]sqlite3\f[R] is used, the database will be located at
99
- \f[V]gemstash.db\f[R] within the directory specified by
100
- \f[V]:base_path\f[R].
101
- The database will automatically be created when using \f[V]sqlite3\f[R].
102
- When \f[V]postgres\f[R], \f[V]mysql\f[R], or \f[V]mysql2\f[R] is used,
103
- the database to connect to must be specified in the \f[V]:db_url\f[R]
104
- configuration key.
76
+ When \f[CR]sqlite3\f[R] is used, the database will be located at
77
+ \f[CR]gemstash.db\f[R] within the directory specified by
78
+ \f[CR]:base_path\f[R].
79
+ The database will automatically be created when using
80
+ \f[CR]sqlite3\f[R].
81
+ When \f[CR]postgres\f[R], \f[CR]mysql\f[R], or \f[CR]mysql2\f[R] is
82
+ used, the database to connect to must be specified in the
83
+ \f[CR]:db_url\f[R] configuration key.
105
84
  The database must already be created when using anything other than
106
- \f[V]sqlite3\f[R].
85
+ \f[CR]sqlite3\f[R].
107
86
  .SS Default value
108
- .PP
109
- \f[V]sqlite3\f[R]
87
+ \f[CR]sqlite3\f[R]
110
88
  .SS Valid values
111
- .PP
112
- \f[V]sqlite3\f[R], \f[V]postgres\f[R], \f[V]mysql\f[R], \f[V]mysql2\f[R]
89
+ \f[CR]sqlite3\f[R], \f[CR]postgres\f[R], \f[CR]mysql\f[R],
90
+ \f[CR]mysql2\f[R]
113
91
  .SH DB URL
92
+ \f[CR]:db_url\f[R]
114
93
  .PP
115
- \f[V]:db_url\f[R]
116
- .PP
117
- Specifies the database to connect to when using \f[V]postgres\f[R],
118
- \f[V]mysql\f[R], or \f[V]mysql2\f[R] for the \f[V]:db_adapter\f[R].
119
- Only used when the \f[V]:db_adapter\f[R] is not \f[V]sqlite3\f[R].
94
+ Specifies the database to connect to when using \f[CR]postgres\f[R],
95
+ \f[CR]mysql\f[R], or \f[CR]mysql2\f[R] for the \f[CR]:db_adapter\f[R].
96
+ Only used when the \f[CR]:db_adapter\f[R] is not \f[CR]sqlite3\f[R].
120
97
  .SS Default value
121
- .PP
122
98
  None
123
99
  .SS Valid values
124
- .PP
125
- A valid database URL for the Sequel gem (http://sequel.jeremyevans.net/)
100
+ A valid database URL for the \c
101
+ .UR http://sequel.jeremyevans.net/
102
+ Sequel gem
103
+ .UE \c
126
104
  .SH DB Connection Options
105
+ \f[CR]:db_connection_options\f[R]
127
106
  .PP
128
- \f[V]:db_connection_options\f[R]
129
- .PP
130
- Specifies additional \f[V]Sequel.connect\f[R] options to use.
107
+ Specifies additional \f[CR]Sequel.connect\f[R] options to use.
131
108
  Note that any options here are merged in with the default options, so
132
- you need not specify the \f[V]max_connections\f[R] if you customize this
133
- option.
109
+ you need not specify the \f[CR]max_connections\f[R] if you customize
110
+ this option.
134
111
  .SS Default value
135
- .PP
136
- \f[V]{ max_connections: 1 }\f[R] for \f[V]sqlite3\f[R] adapter,
137
- \f[V]{ max_connections: config[:puma_threads] + 1 }\f[R] for any other
112
+ \f[CR]{ max_connections: 1 }\f[R] for \f[CR]sqlite3\f[R] adapter,
113
+ \f[CR]{ max_connections: config[:puma_threads] + 1 }\f[R] for any other
138
114
  adapter.
139
115
  .SS Valid values
140
- .PP
141
- A valid connection options Hash for the
142
- Sequel.connect (http://sequel.jeremyevans.net/rdoc/files/doc/opening_databases_rdoc.html#label-General+connection+options)
143
- method.
116
+ A valid connection options Hash for the \c
117
+ .UR http://sequel.jeremyevans.net/rdoc/files/doc/opening_databases_rdoc.html#label-General+connection+options
118
+ Sequel.connect
119
+ .UE \c
120
+ \ method.
144
121
  .SH Rubygems URL
145
- .PP
146
- \f[V]:rubygems_url\f[R]
122
+ \f[CR]:rubygems_url\f[R]
147
123
  .PP
148
124
  Specifies the default gem source URL.
149
- When any API endpoint is called without a \f[V]/private\f[R] or
150
- \f[V]/upstream/<url>\f[R] prefix, this URL will be used to fetch the
125
+ When any API endpoint is called without a \f[CR]/private\f[R] or
126
+ \f[CR]/upstream/<url>\f[R] prefix, this URL will be used to fetch the
151
127
  result.
152
128
  This value can be safely changed even if there are already gems stashed
153
129
  for the previous value.
154
130
  .SS Default value
155
- .PP
156
- \f[V]https://rubygems.org\f[R]
131
+ \f[CR]https://rubygems.org\f[R]
157
132
  .SS Valid values
158
- .PP
159
133
  A valid gem source URL
160
134
  .SH Ignore Gemfile source
161
- .PP
162
- \f[V]:ignore_gemfile_source\f[R]
135
+ \f[CR]:ignore_gemfile_source\f[R]
163
136
  .PP
164
137
  Ignore the source specified in Gemfile and always use
165
- \f[V]:rubygems_url\f[R] as gems upstream.
138
+ \f[CR]:rubygems_url\f[R] as gems upstream.
166
139
  .SS Default value
167
- .PP
168
- \f[V]false\f[R]
140
+ \f[CR]false\f[R]
169
141
  .SS Valid values
170
- .PP
171
- Boolean: \f[V]true\f[R] or \f[V]false\f[R]
142
+ Boolean: \f[CR]true\f[R] or \f[CR]false\f[R]
143
+ .SH Allowed Upstreams
144
+ \f[CR]:allowed_upstreams\f[R]
145
+ .PP
146
+ Specifies the gem sources that clients may ask Gemstash to fetch from,
147
+ whether they use an \f[CR]/upstream/<url>\f[R] or
148
+ \f[CR]/redirect/<url>\f[R] prefix, or the header Bundler sends when
149
+ Gemstash is used as a mirror.
150
+ The gem source specified by \f[CR]:rubygems_url\f[R] is always allowed.
151
+ A request for any other gem source is answered with a \f[CR]403\f[R]
152
+ status, and that gem source is not contacted.
153
+ .PP
154
+ Bundler reports a \f[CR]403\f[R] as
155
+ \f[CR]Access token could not be authenticated\f[R], so that is the error
156
+ someone sees when they bundle with a gem source that is not allowed.
157
+ The actual reason is in the body of the response and in the Gemstash
158
+ log, as a \f[CR]Refusing upstream\f[R] warning.
159
+ .PP
160
+ A gem source is allowed when its scheme, host, port, and path are the
161
+ same as those of an entry.
162
+ Credentials and a trailing slash are ignored, so an entry of
163
+ \f[CR]https://my.gem\-source.local\f[R] allows
164
+ \f[CR]https://user:password\(atmy.gem\-source.local/\f[R], but does not
165
+ allow \f[CR]http://my.gem\-source.local\f[R] or
166
+ \f[CR]https://my.gem\-source.local/private\f[R].
167
+ .PP
168
+ Credentials in an entry are ignored only for that comparison.
169
+ When a client asks for the gem source without credentials of its own,
170
+ Gemstash fetches from it with the credentials of the entry, so anyone
171
+ who can reach Gemstash can read that gem source.
172
+ Gemstash does not pass them on to clients: the requests it answers with
173
+ a redirect, such as \f[CR]/versions\f[R] and \f[CR]/info/*\f[R], reach
174
+ the gem source without credentials.
175
+ This also applies to credentials in \f[CR]:rubygems_url\f[R].
176
+ .PP
177
+ By default only \f[CR]:rubygems_url\f[R] is allowed.
178
+ Before upgrading, list any other Gemfile and mirror sources you use, or
179
+ Bundler requests for them will fail with 403.
180
+ Set \f[CR]\(dq*\(dq\f[R] only if you deliberately accept arbitrary
181
+ client\-selected sources.
182
+ Redirects from an allowed source to an unlisted source are refused.
183
+ If an allowed source redirects gem downloads to a CDN, list the CDN in
184
+ \f[CR]:allowed_redirects\f[R].
185
+ Redirect targets containing credentials are refused.
186
+ .SS Default value
187
+ \f[CR][]\f[R] (only \f[CR]:rubygems_url\f[R])
188
+ .SS Valid values
189
+ \f[CR]\(dq*\(dq\f[R] to allow any gem source, or a list of gem source
190
+ URLs.
191
+ An empty list allows only the gem source specified by
192
+ \f[CR]:rubygems_url\f[R].
193
+ .PP
194
+ Each URL needs a host, and its scheme, if it has one, must be
195
+ \f[CR]http://\f[R] or \f[CR]https://\f[R].
196
+ \f[CR]gemstash start\f[R] refuses a configuration with any other entry.
197
+ The error gives the position of the entry in the list and not its value,
198
+ because the value may contain credentials.
199
+ .SH Allowed Redirects
200
+ \f[CR]:allowed_redirects\f[R]
201
+ .PP
202
+ Specifies further URLs that a fetch from an allowed gem source may be
203
+ redirected to, such as the CDN a gem server sends its downloads to.
204
+ Clients cannot ask Gemstash to use these as gem sources.
205
+ \f[CR]:rubygems_url\f[R] and the entries of
206
+ \f[CR]:allowed_upstreams\f[R] are always valid redirect targets.
207
+ .PP
208
+ A redirect is followed when its scheme, host, and port are those of an
209
+ entry and its path is the path of the entry or lies below it.
210
+ An \f[CR]http\f[R] entry also accepts the same host over
211
+ \f[CR]https\f[R], and a redirect from \f[CR]https\f[R] to
212
+ \f[CR]http\f[R] is never followed.
213
+ Paths are compared segment by segment, and a redirect below an entry
214
+ with a path is refused when a segment could be resolved to another path,
215
+ such as \f[CR]..;\f[R] or a doubly encoded \f[CR]..\f[R].
216
+ Do not rely on the path of an entry alone to keep gem sources on one
217
+ host apart: the access control of that host is what separates them.
218
+ .SS Default value
219
+ \f[CR][]\f[R]
220
+ .SS Valid values
221
+ A list of URLs, checked like the entries of
222
+ \f[CR]:allowed_upstreams\f[R].
223
+ \f[CR]\(dq*\(dq\f[R] is not supported.
172
224
  .SH Puma Threads
173
- .PP
174
- \f[V]:puma_threads\f[R]
225
+ \f[CR]:puma_threads\f[R]
175
226
  .PP
176
227
  Specifies the number of threads used for the Gemstash server.
177
228
  .SS Default value
178
- .PP
179
- \f[V]16\f[R]
229
+ \f[CR]16\f[R]
180
230
  .SS Valid values
181
- .PP
182
- Integer value with a minimum of \f[V]1\f[R]
231
+ Integer value with a minimum of \f[CR]1\f[R]
183
232
  .SH Bind Address
184
- .PP
185
- \f[V]:bind\f[R]
233
+ \f[CR]:bind\f[R]
186
234
  .PP
187
235
  Specifies the binding used to start the Gemstash server.
188
236
  Keep in mind the user starting Gemstash needs to have access to bind in
@@ -190,67 +238,96 @@ this manner.
190
238
  For example, if you use a port below 1024, you will need to run Gemstash
191
239
  as the root user.
192
240
  .SS Default value
193
- .PP
194
- \f[V]tcp://0.0.0.0:9292\f[R]
241
+ \f[CR]tcp://0.0.0.0:9292\f[R]
195
242
  .SS Valid values
196
- .PP
197
- Any valid binding that is supported by
198
- Puma (https://github.com/puma/puma#binding-tcp--sockets)
243
+ Any valid binding that \c
244
+ .UR https://github.com/puma/puma#binding-tcp--sockets
245
+ is supported by Puma
246
+ .UE \c
199
247
  .SH Protected Fetch
200
- .PP
201
- \f[V]:protected_fetch\f[R]
248
+ \f[CR]:protected_fetch\f[R]
202
249
  .PP
203
250
  Tells Gemstash to authenticate via an API key before allowing the
204
251
  fetching of private gems and specs.
205
252
  The default behavior is to allow unauthenticated download of private
206
253
  gems and specs.
207
254
  .SS Default value
208
- .PP
209
- \f[V]false\f[R]
255
+ \f[CR]false\f[R]
210
256
  .SS Valid values
211
- .PP
212
- Boolean values \f[V]true\f[R] or \f[V]false\f[R]
257
+ Boolean values \f[CR]true\f[R] or \f[CR]false\f[R]
213
258
  .SH Fetch Timeout
214
- .PP
215
- \f[V]:fetch_timeout\f[R]
216
- .PP
217
- This is the number of seconds to allow for fetching a gem from upstream.
218
- It covers establishing the connection and receiving the response.
219
- Fetching gems over a slow connection may cause timeout errors.
220
- If you experience timeout errors, you may want to increase this value.
221
- The default is \f[V]20\f[R] seconds.
259
+ \f[CR]:fetch_timeout\f[R]
260
+ .PP
261
+ This is the number of seconds to wait for an upstream read, not the
262
+ total download time.
263
+ A connection that keeps delivering data can take longer;
264
+ \f[CR]:max_upstream_duration\f[R] bounds the entire request.
265
+ After \f[CR]:fetch_timeout\f[R] seconds, the upstream connection must
266
+ also average at least 1 KiB/s across all response bytes, including
267
+ headers, redirects, chunk metadata and trailers, to prevent a connection
268
+ that drips one byte at a time from holding a worker.
269
+ Fetching gems over a very slow connection may cause timeout errors.
270
+ The default is \f[CR]20\f[R] seconds.
222
271
  .SS Default value
223
- .PP
224
- \f[V]20\f[R]
272
+ \f[CR]20\f[R]
225
273
  .SS Valid values
226
- .PP
227
- Integer value with a minimum of \f[V]1\f[R]
274
+ Positive finite number of seconds (including fractions); \f[CR]nil\f[R]
275
+ is not supported
276
+ .SH Max Upstream Duration
277
+ \f[CR]:max_upstream_duration\f[R]
278
+ .PP
279
+ Maximum seconds for an entire upstream request, including redirects and
280
+ streaming the body.
281
+ Slow but steady downloads may exceed \f[CR]:fetch_timeout\f[R] without
282
+ exceeding this limit.
283
+ Increase it if legitimate downloads need longer than five minutes.
284
+ .SS Default value
285
+ \f[CR]300\f[R] seconds
286
+ .SS Valid values
287
+ Positive finite number of seconds (including fractions); \f[CR]nil\f[R]
288
+ is not supported
228
289
  .SH Open Timeout
229
- .PP
230
- \f[V]:open_timeout\f[R]
290
+ \f[CR]:open_timeout\f[R]
231
291
  .PP
232
292
  The timeout setting for opening the connection to an upstream gem
233
293
  server.
234
- On high-latency networks, even establishing the connection to an
294
+ On high\-latency networks, even establishing the connection to an
235
295
  upstream gem server can take a while.
236
296
  If you experience connection failures instead of timeout errors, you may
237
297
  want to increase this value.
238
- The default is \f[V]2\f[R] seconds.
298
+ The default is \f[CR]2\f[R] seconds.
239
299
  .SS Default value
240
- .PP
241
- \f[V]2\f[R]
300
+ \f[CR]2\f[R]
242
301
  .SS Valid values
302
+ Integer value with a minimum of \f[CR]1\f[R]
303
+ .SH Max Upstream Bytes
304
+ \f[CR]:max_upstream_bytes\f[R]
243
305
  .PP
244
- Integer value with a minimum of \f[V]1\f[R]
306
+ The size in bytes of the largest response to accept from an upstream gem
307
+ server.
308
+ This applies to every gem, gemspec, index of specs, and list of
309
+ dependencies that is fetched.
310
+ A larger response is abandoned while it is being downloaded and is not
311
+ stashed, and the request for it fails.
312
+ The size is that of the response after any compression used to transfer
313
+ it has been undone.
314
+ Make sure the value is larger than the largest gem you need.
315
+ Response headers are limited to 64 KiB total, and each chunk metadata
316
+ line to 64 KiB.
317
+ A response can use about twice the byte cap while buffers grow (over 2
318
+ GiB with 16 default Puma threads).
319
+ Increase this limit if your upstream has larger gems.
320
+ .SS Default value
321
+ \f[CR]67108864\f[R] (64 MiB)
322
+ .SS Valid values
323
+ Positive integer, or \f[CR]nil\f[R] to disable the body cap (not
324
+ recommended)
245
325
  .SH Log File
246
- .PP
247
- \f[V]:log_file\f[R]
326
+ \f[CR]:log_file\f[R]
248
327
  .PP
249
328
  Indicates the name of the file to use for logging.
250
329
  The file will be placed in the base path.
251
330
  .SS Default value
252
- .PP
253
- \f[V]server.log\f[R]
331
+ \f[CR]server.log\f[R]
254
332
  .SS Valid values
255
- .PP
256
- Any valid file name, or \f[V]:stdout\f[R] to log to \f[V]$stdout\f[R]
333
+ Any valid file name, or \f[CR]:stdout\f[R] to log to \f[CR]$stdout\f[R]