120 lines
4.8 KiB
YAML
120 lines
4.8 KiB
YAML
package_name: httprc
|
|
output: options_gen.go
|
|
interfaces:
|
|
- name: RegisterOption
|
|
comment: |
|
|
RegisterOption desribes options that can be passed to `(httprc.Cache).Register()`
|
|
- name: CacheOption
|
|
comment: |
|
|
CacheOption desribes options that can be passed to `New()`
|
|
- name: FetcherOption
|
|
methods:
|
|
- cacheOption
|
|
comment: |
|
|
FetcherOption describes options that can be passed to `(httprc.Fetcher).NewFetcher()`
|
|
- name: FetchOption
|
|
comment: |
|
|
FetchOption describes options that can be passed to `(httprc.Fetcher).Fetch()`
|
|
- name: FetchRegisterOption
|
|
methods:
|
|
- fetchOption
|
|
- registerOption
|
|
- name: FetchFetcherRegisterOption
|
|
methods:
|
|
- fetchOption
|
|
- fetcherOption
|
|
- registerOption
|
|
options:
|
|
- ident: FetcherWorkerCount
|
|
interface: FetcherOption
|
|
argument_type: int
|
|
comment: |
|
|
WithFetchWorkerCount specifies the number of HTTP fetch workers that are spawned
|
|
in the backend. By default 3 workers are spawned.
|
|
- ident: Whitelist
|
|
interface: FetchFetcherRegisterOption
|
|
argument_type: Whitelist
|
|
comment: |
|
|
WithWhitelist specifies the Whitelist object that can control which URLs are
|
|
allowed to be processed.
|
|
|
|
It can be passed to `httprc.NewCache` as a whitelist applied to all
|
|
URLs that are fetched by the cache, or it can be passed on a per-URL
|
|
basis using `(httprc.Cache).Register()`. If both are specified,
|
|
the url must fulfill _both_ the cache-wide whitelist and the per-URL
|
|
whitelist.
|
|
- ident: Transformer
|
|
interface: RegisterOption
|
|
argument_type: Transformer
|
|
comment: |
|
|
WithTransformer specifies the `httprc.Transformer` object that should be applied
|
|
to the fetched resource. The `Transform()` method is only called if the HTTP request
|
|
returns a `200 OK` status.
|
|
- ident: HTTPClient
|
|
interface: FetchRegisterOption
|
|
argument_type: HTTPClient
|
|
comment: |
|
|
WithHTTPClient specififes the HTTP Client object that should be used to fetch
|
|
the resource. For example, if you need an `*http.Client` instance that requires
|
|
special TLS or Authorization setup, you might want to pass it using this option.
|
|
- ident: MinRefreshInterval
|
|
interface: RegisterOption
|
|
argument_type: time.Duration
|
|
comment: |
|
|
WithMinRefreshInterval specifies the minimum refresh interval to be used.
|
|
|
|
When we fetch the key from a remote URL, we first look at the `max-age`
|
|
directive from `Cache-Control` response header. If this value is present,
|
|
we compare the `max-age` value and the value specified by this option
|
|
and take the larger one (e.g. if `max-age` = 5 minutes and `min refresh` = 10
|
|
minutes, then next fetch will happen in 10 minutes)
|
|
|
|
Next we check for the `Expires` header, and similarly if the header is
|
|
present, we compare it against the value specified by this option,
|
|
and take the larger one.
|
|
|
|
Finally, if neither of the above headers are present, we use the
|
|
value specified by this option as the interval until the next refresh.
|
|
|
|
If unspecified, the minimum refresh interval is 1 hour.
|
|
|
|
This value and the header values are ignored if `WithRefreshInterval` is specified.
|
|
- ident: RefreshInterval
|
|
interface: RegisterOption
|
|
argument_type: time.Duration
|
|
comment: |
|
|
WithRefreshInterval specifies the static interval between refreshes
|
|
of resources controlled by `httprc.Cache`.
|
|
|
|
Providing this option overrides the adaptive token refreshing based
|
|
on Cache-Control/Expires header (and `httprc.WithMinRefreshInterval`),
|
|
and refreshes will *always* happen in this interval.
|
|
|
|
You generally do not want to make this value too small, as it can easily
|
|
be considered a DoS attack, and there is no backoff mechanism for failed
|
|
attempts.
|
|
- ident: RefreshWindow
|
|
interface: CacheOption
|
|
argument_type: time.Duration
|
|
comment: |
|
|
WithRefreshWindow specifies the interval between checks for refreshes.
|
|
`httprc.Cache` does not check for refreshes in exact intervals. Instead,
|
|
it wakes up at every tick that occurs in the interval specified by
|
|
`WithRefreshWindow` option, and refreshes all entries that need to be
|
|
refreshed within this window.
|
|
|
|
The default value is 15 minutes.
|
|
|
|
You generally do not want to make this value too small, as it can easily
|
|
be considered a DoS attack, and there is no backoff mechanism for failed
|
|
attempts.
|
|
- ident: ErrSink
|
|
interface: CacheOption
|
|
argument_type: ErrSink
|
|
comment: |
|
|
WithErrSink specifies the `httprc.ErrSink` object that handles errors
|
|
that occurred during the cache's execution. For example, you will be
|
|
able to intercept errors that occurred during the execution of Transformers.
|
|
|
|
|