github.com/lestrrat-go/jwx/v2@v2.0.21/docs/20-global-settings.md (about)

     1  # Global Settings
     2  
     3  ## Enabling Optional Signature Methods
     4  
     5  Some algorithms are intentionally left out because they are not as common in the wild, and you may want to avoid compiling this extra information in.
     6  To enable these, you must explicitly provide a build tag.
     7  
     8  | Algorithm        | Build Tag  |
     9  |:-----------------|:-----------|
    10  | secp256k1/ES256K | jwx_es256k |
    11  
    12  If you do not provide these tags, the program will still compile, but it will return an error during runtime saying that these algorithms are not supported.
    13  
    14  ## Switching to a faster JSON library
    15  
    16  By default we use the standard library's `encoding/json` for all of our JSON needs.
    17  However, if performance for parsing/serializing JSON is really important to you, you might want to enable [github.com/goccy/go-json](https://github.com/goccy/go-json) by enabling the `jwx_goccy` tag.
    18  
    19  ```shell
    20  % go build -tags jwx_goccy ...
    21  ```
    22  
    23  [github.com/goccy/go-json](https://github.com/goccy/go-json) is *disabled* by default because it uses some really advanced black magic, and I really do not feel like debugging it **IF** it breaks. Please note that that's a big "if".
    24  As of github.com/goccy/go-json@v0.3.3 I haven't see any problems, and I would say that it is mostly stable.
    25  
    26  However, it is a dependency that you can go without, and I won't be of much help if it breaks -- therefore it is not the default.
    27  If you know what you are doing, I highly recommend enabling this module -- all you need to do is to enable this tag.
    28  Disable the tag if you feel like it's not worth the hassle.
    29  
    30  And when you *do* enable [github.com/goccy/go-json](https://github.com/goccy/go-json) and you encounter some mysterious error, I also trust that you know to file an issue to [github.com/goccy/go-json](https://github.com/goccy/go-json) and **NOT** to this library.
    31  
    32  ## Enabling experimental base64 encoder/decoder
    33  
    34  This feature is currently considered experimental.
    35  
    36  Currently you can enable [github.com/segmentio/asm/base64](https://github.com/segmentio/asm/tree/main/base64) by specifying the `jwx_asmbase64` build tag
    37  
    38  ```shell
    39  % go build -tags jwx_goccy ...
    40  ```
    41  
    42  In our limited testing, this does not seem to improve performance significantly: presumably the other bottlenecks are more dominant. If you care enough to use this option, you probably wantt o enable `jwx_goccy` build tag as well.
    43  
    44  ## Using json.Number
    45  
    46  If you want to parse numbers in the incoming JSON objects as json.Number
    47  instead of floats, you can use the following call to globally affect the behavior of JSON parsing.
    48  
    49  ```go
    50  func init() {
    51    jwx.DecoderSettings(jwx.WithUseNumber(true))
    52  }
    53  ```
    54  
    55  Do be aware that this has *global* effect. All code that calls in to `encoding/json`
    56  within `jwx` *will* use your settings.
    57  
    58  ## Decode private fields to objects
    59  
    60  Packages within `github.com/lestrrat-go/jwx/v2` parses known fields into pre-defined types,
    61  but for everything else (usually called private fields/headers/claims) are decoded into
    62  wharever `"encoding/json".Unmarshal` deems appropriate.
    63  
    64  For example, JSON objects are converted to `map[string]interface{}`, JSON arrays into
    65  `[]interface{}`, and so on.
    66  
    67  Sometimes you know beforehand that it makes sense for certain fields to be decoded into
    68  proper objects instead of generic maps or arrays. When you encounter this, you can use
    69  the `RegisterCustomField()` method in each of `jwe`, `jwk`, `jws`, and `jwt` packages.
    70  
    71  ```go
    72  func init() {
    73    jwt.RegisterCustomField(`x-foo-bar`, mypkg.FooBar{})
    74  }
    75  ```
    76  
    77  This tells the decoder that when it encounters a JWT token with the field named
    78  `"x-foo-bar"`, it should be decoded to an instance of `mypkg.FooBar`. Then you can
    79  access this value by using `Get()`
    80  
    81  ```go
    82  v, _ := token.Get(`x-foo-bar`)
    83  foobar := v.(mypkg.FooBar)
    84  ```
    85  
    86  Do be aware that this has *global* effect. In the above example, all JWT tokens containing
    87  the `"x-foo-bar"` key will decode in the same way. If you need this behavior from
    88  `jwe`, `jwk`, or `jws` packages, you need to do the same thing for each package.
    89  
    90