autodoc updates

docs/01-jwt.md

@@ -392,8 +392,8 @@ func ExampleJWT_ParseWithKeySet() {
  // all of the public keys
  {
  privset := jwk.NewSet()
- privset.Add(realKey)
- privset.Add(bogusKey)
+ privset.AddKey(realKey)
+ privset.AddKey(bogusKey)
  v, err := jwk.PublicSetOf(privset)
  if err != nil {
  fmt.Printf("failed to create public JWKS: %s\n", err)
@@ -610,7 +610,7 @@ func ExampleJWT_ParseWithJKU() {
  fmt.Printf("failed to create public key: %s\n", err)
  return
  }
- set.Add(pubkey)
+ set.AddKey(pubkey)
  }
 
  srv := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {

docs/02-jws.md

@@ -370,14 +370,14 @@ func ExampleJWS_VerifyWithJWKSet() {
  set := jwk.NewSet()
  // Add some bogus keys
  k1, _ := jwk.FromRaw([]byte("abracadavra"))
- set.Add(k1)
+ set.AddKey(k1)
  k2, _ := jwk.FromRaw([]byte("opensasame"))
- set.Add(k2)
- // Add the real thing
+ set.AddKey(k2)
+ // AddKey the real thing
  pubkey, _ := jwk.PublicRawKeyOf(privkey)
  k3, _ := jwk.FromRaw(pubkey)
  k3.Set(jwk.AlgorithmKey, jwa.RS256)
- set.Add(k3)
+ set.AddKey(k3)
 
  // Up to this point, you probably will replace with a simple jwk.Fetch()
 

docs/03-jwe.md

@@ -416,13 +416,13 @@ func ExampleJWE_VerifyWithJWKSet() {
  set := jwk.NewSet()
  // Add some bogus keys
  k1, _ := jwk.FromRaw([]byte("abracadavra"))
- set.Add(k1)
+ set.AddKey(k1)
  k2, _ := jwk.FromRaw([]byte("opensasame"))
- set.Add(k2)
+ set.AddKey(k2)
  // Add the real thing
  k3, _ := jwk.FromRaw(privkey)
  k3.Set(jwk.AlgorithmKey, jwa.RSA_OAEP)
- set.Add(k3)
+ set.AddKey(k3)
 
  // Up to this point, you probably will replace with a simple jwk.Fetch()
 

docs/04-jwk.md

@@ -670,6 +670,49 @@ source: [examples/jwk_cache_example_test.go](https://github.com/lestrrat-go/jwx/
 <!-- END INCLUDE -->
 
 <!-- INCLUDE(examples/jwk_cached_set_example_test.go) -->
+```go
+package examples_test
+
+import (
+ "context"
+ "fmt"
+ "time"
+
+ "github.com/lestrrat-go/jwx/v2/jwk"
+ "github.com/lestrrat-go/jwx/v2/jws"
+)
+
+func ExampleJWK_CachedSet() {
+ ctx, cancel := context.WithCancel(context.Background())
+ defer cancel()
+
+ const googleCerts = `https://www.googleapis.com/oauth2/v3/certs`
+
+ // The first steps are the same as examples/jwk_cache_example_test.go
+ c := jwk.NewCache(ctx)
+ c.Register(googleCerts, jwk.WithMinRefreshInterval(15*time.Minute))
+ _, err := c.Refresh(ctx, googleCerts)
+ if err != nil {
+ fmt.Printf("failed to refresh google JWKS: %s\n", err)
+ return
+ }
+
+ cached := jwk.NewCachedSet(c, googleCerts)
+
+ // cached fulfills the jwk.Set interface.
+ var _ jwk.Set = cached
+
+ // That means you can pass it to things like jws.WithKeySet,
+ // allowing you to pretend as if you are using the result of
+ //
+ // jwk.Fetch(ctx, googleCerts)
+ //
+ // But you are instead using a cached (and periodically refreshed)
+ // for each operation.
+ _ = jws.WithKeySet(cached)
+}
+```
+source: [examples/jwk_cached_set_example_test.go](https://github.com/lestrrat-go/jwx/blob/v2/examples/jwk_cached_set_example_test.go)
 <!-- END INCLUDE -->
 
 ## Using Whitelists