github.com/lestrrat-go/jwx/v2@v2.0.21/jwk/options.yaml (about)

     1  package_name: jwk
     2  output: jwk/options_gen.go
     3  interfaces:
     4    - name: CacheOption
     5      comment: |
     6        CacheOption is a type of Option that can be passed to the
     7        the `jwk.NewCache()` function.
     8    - name: AssignKeyIDOption
     9    - name: FetchOption
    10      methods:
    11        - fetchOption
    12        - parseOption
    13        - registerOption
    14      comment: |
    15        FetchOption is a type of Option that can be passed to `jwk.Fetch()`
    16        FetchOption also implements the `RegisterOption`, and thus can
    17        safely be passed to `(*jwk.Cache).Register()`
    18    - name: ParseOption
    19      methods:
    20        - fetchOption
    21        - registerOption
    22        - readFileOption
    23      comment: |
    24        ParseOption is a type of Option that can be passed to `jwk.Parse()`
    25        ParseOption also implmentsthe `ReadFileOption` and `CacheOption`,
    26        and thus safely be passed to `jwk.ReadFile` and `(*jwk.Cache).Configure()`
    27    - name: ReadFileOption
    28      comment: |
    29        ReadFileOption is a type of `Option` that can be passed to `jwk.ReadFile`
    30    - name: RegisterOption
    31      comment: |
    32        RegisterOption desribes options that can be passed to `(jwk.Cache).Register()`
    33  options:
    34    - ident: HTTPClient
    35      interface: FetchOption
    36      argument_type: HTTPClient
    37      comment: |
    38        WithHTTPClient allows users to specify the "net/http".Client object that
    39        is used when fetching jwk.Set objects.
    40    - ident: ThumbprintHash
    41      interface: AssignKeyIDOption
    42      argument_type: crypto.Hash
    43    - ident: RefreshInterval
    44      interface: RegisterOption
    45      argument_type: time.Duration
    46      comment: |
    47        WithRefreshInterval specifies the static interval between refreshes
    48        of jwk.Set objects controlled by jwk.Cache.
    49        
    50        Providing this option overrides the adaptive token refreshing based
    51        on Cache-Control/Expires header (and jwk.WithMinRefreshInterval),
    52        and refreshes will *always* happen in this interval.
    53    - ident: MinRefreshInterval
    54      interface: RegisterOption
    55      argument_type: time.Duration
    56      comment: |
    57        WithMinRefreshInterval specifies the minimum refresh interval to be used
    58        when using `jwk.Cache`. This value is ONLY used if you did not specify
    59        a user-supplied static refresh interval via `WithRefreshInterval`.
    60        
    61        This value is used as a fallback value when tokens are refreshed.
    62        
    63        When we fetch the key from a remote URL, we first look at the max-age
    64        directive from Cache-Control response header. If this value is present,
    65        we compare the max-age value and the value specified by this option
    66        and take the larger one.
    67        
    68        Next we check for the Expires header, and similarly if the header is
    69        present, we compare it against the value specified by this option,
    70        and take the larger one.
    71        
    72        Finally, if neither of the above headers are present, we use the
    73        value specified by this option as the next refresh timing
    74        
    75        If unspecified, the minimum refresh interval is 1 hour
    76    - ident: LocalRegistry
    77      option_name: withLocalRegistry
    78      interface: ParseOption
    79      argument_type: '*json.Registry'
    80      comment: This option is only available for internal code. Users don't get to play with it
    81    - ident: PEM
    82      interface: ParseOption
    83      argument_type: bool
    84      comment: WithPEM specifies that the input to `Parse()` is a PEM encoded key.
    85    - ident: FetchWhitelist
    86      interface: FetchOption
    87      argument_type: Whitelist
    88      comment: |
    89        WithFetchWhitelist specifies the Whitelist object to use when
    90        fetching JWKs from a remote source. This option can be passed
    91        to both `jwk.Fetch()`, `jwk.NewCache()`, and `(*jwk.Cache).Configure()`
    92    - ident: IgnoreParseError
    93      interface: ParseOption
    94      argument_type: bool
    95      comment: |
    96        WithIgnoreParseError is only applicable when used with `jwk.Parse()`
    97        (i.e. to parse JWK sets). If passed to `jwk.ParseKey()`, the function
    98        will return an error no matter what the input is.
    99        
   100        DO NOT USE WITHOUT EXHAUSTING ALL OTHER ROUTES FIRST.
   101        
   102        The option specifies that errors found during parsing of individual
   103        keys are ignored. For example, if you had keys A, B, C where B is
   104        invalid (e.g. it does not contain the required fields), then the
   105        resulting JWKS will contain keys A and C only.
   106        
   107        This options exists as an escape hatch for those times when a
   108        key in a JWKS that is irrelevant for your use case is causing
   109        your JWKS parsing to fail, and you want to get to the rest of the
   110        keys in the JWKS.
   111        
   112        Again, DO NOT USE unless you have exhausted all other routes.
   113        When you use this option, you will not be able to tell if you are
   114        using a faulty JWKS, except for when there are JSON syntax errors.
   115    - ident: FS
   116      interface: ReadFileOption
   117      argument_type: fs.FS
   118      comment: |
   119        WithFS specifies the source `fs.FS` object to read the file from.
   120    - ident: PostFetcher
   121      interface: RegisterOption
   122      argument_type: PostFetcher
   123      comment: |
   124        WithPostFetcher specifies the PostFetcher object to be used on the
   125        jwk.Set object obtained in `jwk.Cache`. This option can be used
   126        to, for example, modify the jwk.Set to give it key IDs or algorithm
   127        names after it has been fetched and parsed, but before it is cached.
   128    - ident: RefreshWindow
   129      interface: CacheOption
   130      argument_type: time.Duration
   131      comment: |
   132        WithRefreshWindow specifies the interval between checks for refreshes.
   133  
   134        See the documentation in `httprc.WithRefreshWindow` for more details.
   135    - ident: ErrSink
   136      interface: CacheOption
   137      argument_type: ErrSink
   138      comment: |
   139        WithErrSink specifies the `httprc.ErrSink` object that handles errors
   140        that occurred during the cache's execution.
   141  
   142        See the documentation in `httprc.WithErrSink` for more details.