Initial v3 code

.github/dependabot.yml

@@ -5,6 +5,21 @@
 
 version: 2
 updates:
+  - package-ecosystem: "gomod" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "daily"
+    target-branch: "v3"
+    labels:
+      - "go"
+      - "dependencies"
+      - "dependabot"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    target-branch: "v3"
+
   - package-ecosystem: "gomod" # See documentation for possible values
     directory: "/" # Location of package manifests
     schedule:
@@ -18,5 +33,5 @@ updates:
     directory: "/"
     schedule:
       interval: "daily"
-    target-branch: "main"
+    target-branch: "v2"
 

.github/workflows/autodoc.yml

@@ -12,8 +12,8 @@ jobs:
     name: "Run commands to generate documentation"
     if: github.event.pull_request.merged == true
     steps:
-      - name: Checkout repository
-        uses: actions/checkout@v2
+      - name: Checkout repositor
+        uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
       - name: Process markdown files
         run: |
           find . -name '*.md' | xargs perl tools/autodoc.pl

.github/workflows/ci.yml

@@ -6,23 +6,18 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        go: [ '1.21', '1.20' ]
+        go: [ '1.23', '1.22' ]
     name: Go ${{ matrix.go }} test
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
       - name: Check documentation generator
         run: |
           find . -name '*.md' | xargs env AUTODOC_DRYRUN=1 perl tools/autodoc.pl
       - name: Install Go stable version
-        uses: actions/setup-go@v5
+        uses: actions/setup-go@0a12ed9d6a96ab950c8f026ed9f722fe0da7ef32 # v5.0.2
         with:
           go-version: ${{ matrix.go }}
       - name: Test
-        run: go test -v -race -coverprofile=coverage.out -coverpkg=./... ./...
-      - name: Upload code coverage to codecov
-        if: matrix.go == '1.19'
-        uses: codecov/codecov-action@v3
-        with:
-          file: ./coverage.out
+        run: go test -v -race 
 

.github/workflows/lint.yml

@@ -5,14 +5,13 @@ jobs:
     name: lint
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-go@v5
+      - name: Checkout repository
+        uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
+      - name: Install Go stable version
+        uses: actions/setup-go@0a12ed9d6a96ab950c8f026ed9f722fe0da7ef32 # v5.0.2
         with:
-          go-version: 1.21
-          check-latest: true
-      - uses: golangci/golangci-lint-action@v3
-        with:
-          version: v1.54.2
+          go-version-file: go.mod
+      - uses: golangci/golangci-lint-action@aaa42aa0628b4ae2578232a66b541047968fac86 # v6.1.0
       - name: Run go vet
         run: |
           go vet ./...

Changes

@@ -1,6 +1,10 @@
 Changes
 =======
 
+v3.0.0 UNRELEASED
+[Breaking Changes]
+  * The entire API has been re-imagined for Go versions that allow typed parameters
+
 v2.0.0 19 Feb 2024
 [Breaking Changes]
   * `Fetcher` type is no longer available. You probably want to provide

README.md

@@ -6,126 +6,61 @@ refreshing.
 
 # SYNOPSIS
 
-<!-- INCLUDE(httprc_example_test.go) -->
+<!-- INCLUDE(client_example_test.go) -->
 ```go
 package httprc_test
 
 import (
-  "context"
-  "fmt"
-  "net/http"
-  "net/http/httptest"
-  "sync"
-  "time"
-
-  "github.com/lestrrat-go/httprc/v2"
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"time"
+
+	"github.com/lestrrat-go/httprc/v3"
 )
 
-const (
-  helloWorld   = `Hello World!`
-  goodbyeWorld = `Goodbye World!`
-)
-
-func ExampleCache() {
-  var mu sync.RWMutex
-
-  msg := helloWorld
-
-  srv := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-    w.Header().Set(`Cache-Control`, fmt.Sprintf(`max-age=%d`, 2))
-    w.WriteHeader(http.StatusOK)
-    mu.RLock()
-    fmt.Fprint(w, msg)
-    mu.RUnlock()
-  }))
-  defer srv.Close()
-
-  ctx, cancel := context.WithCancel(context.Background())
-  defer cancel()
+func ExampleClient() {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
 
-  errSink := httprc.ErrSinkFunc(func(err error) {
-    fmt.Printf("%s\n", err)
-  })
+	type HelloWorld struct {
+		Hello string `json:"hello"`
+	}
 
-  c := httprc.NewCache(ctx,
-    httprc.WithErrSink(errSink),
-    httprc.WithRefreshWindow(time.Second), // force checks every second
-  )
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		json.NewEncoder(w).Encode(map[string]string{"hello": "world"})
+	}))
 
-  c.Register(srv.URL,
-    httprc.WithHTTPClient(srv.Client()),        // we need client with TLS settings
-    httprc.WithMinRefreshInterval(time.Second), // allow max-age=1 (smallest)
-  )
+	// Create a new client
+	cl := httprc.NewClient()
 
-  payload, err := c.Get(ctx, srv.URL)
-  if err != nil {
-    fmt.Printf("%s\n", err)
-    return
-  }
+	// Start the client, and obtain a Controller object
+	ctrl, err := cl.Run(ctx)
+	if err != nil {
+		fmt.Println(err.Error())
+		return
+	}
 
-  if string(payload.([]byte)) != helloWorld {
-    fmt.Printf("payload mismatch: %s\n", payload)
-    return
-  }
+	r, err := httprc.NewResource[HelloWorld](srv.URL, httprc.JSONTransformer[HelloWorld]())
+	if err != nil {
+		fmt.Println(err.Error())
+		return
+	}
 
-  mu.Lock()
-  msg = goodbyeWorld
-  mu.Unlock()
+	// Add the resource to the controller, so that it starts fetching
+	ctrl.AddResource(r)
 
-  time.Sleep(4 * time.Second)
+	time.Sleep(1 * time.Second)
 
-  payload, err = c.Get(ctx, srv.URL)
-  if err != nil {
-    fmt.Printf("%s\n", err)
-    return
-  }
-
-  if string(payload.([]byte)) != goodbyeWorld {
-    fmt.Printf("payload mismatch: %s\n", payload)
-    return
-  }
+	m := r.Resource()
+	fmt.Println(m.Hello)
+	// OUTPUT:
+	// world
+}
 
-  cancel()
 
-  // OUTPUT:
-}
-```
-source: [httprc_example_test.go](https://github.com/lestrrat-go/jwx/blob/main/httprc_example_test.go)
-<!-- END INCLUDE -->
-
-# Sequence Diagram
-
-```mermaid
-sequenceDiagram
-  autonumber
-  actor User
-  participant httprc.Cache
-  participant httprc.registry
-  participant httprc.HTTPClient
-  User->>httprc.Cache: Fetch URL `u`
-  activate httprc.registry
-  httprc.Cache->>httprc.registry: Fetch local cache for `u`
-  alt Cache exists
-    httprc.registry-->httprc.Cache: Return local cache
-    httprc.Cache-->>User: Return data
-    Note over httprc.registry: If the cache exists, there's nothing more to do.<br />The cached content will be updated periodically in httprc.queue
-    deactivate httprc.registry
-  else Cache does not exist
-    activate httprc.HTTPClient
-    httprc.Cache->>httprc.HTTPClient: Fetch remote resource `u`
-    httprc.HTTPClient-->>httprc.Cache: Return fetched data
-    deactivate httprc.HTTPClient
-    httprc.Cache-->>User: Return data
-    httprc.Cache-)httprc.queue: Enqueue into auto-refresh queue
-    activate httprc.queue
-    loop queue Loop
-      Note over httprc.registry,httprc.Fetcher: Cached contents are updated synchronously
-      httprc.queue->>httprc.queue: Wait until next refresh
-      httprc.queue-->>httprc.Fetcher: Request fetch
-      httprc.HTTPClient->>httprc.queue: Return fetched data
-      httprc.queue-->>httprc.registry: Store new version in cache
-      httprc.queue->>httprc.queue: Enqueue into auto-refresh queue (again)
-    end
-    deactivate httprc.queue
-  end
 ```
+source: [client_example_test.go](https://github.com/lestrrat-go/httprc/blob/main/client_example_test.go)
+<!-- END INCLUDE -->