diff --git a/pkg/api/cache.go b/pkg/api/cache.go index 7085d05..94a5e28 100644 --- a/pkg/api/cache.go +++ b/pkg/api/cache.go @@ -123,6 +123,9 @@ func (crt cacheRoundTripper) RoundTrip(req *http.Request) (*http.Response, error // Allow an individual request to override cache options. func requestCacheOptions(req *http.Request) (string, time.Duration) { var dur time.Duration + // Added alongside the TTL header in https://github.com/cli/go-gh/pull/49. + // No production consumer of the directory override is known; retain it for + // compatibility. dir := req.Header.Get("X-GH-CACHE-DIR") ttl := req.Header.Get("X-GH-CACHE-TTL") if ttl != "" { @@ -170,46 +173,91 @@ func (fs *fileStorage) read(key string) (*http.Response, error) { return res, err } -func (fs *fileStorage) store(key string, res *http.Response) (storeErr error) { - cacheFile := fs.filePath(key) - +func (fs *fileStorage) store(key string, res *http.Response) error { fs.mu.Lock() defer fs.mu.Unlock() - if storeErr = os.MkdirAll(filepath.Dir(cacheFile), 0755); storeErr != nil { - return + cacheFilePath := fs.filePath(key) + dir := filepath.Dir(cacheFilePath) + if err := os.MkdirAll(dir, 0755); err != nil { + return err } - var f *os.File - if f, storeErr = os.OpenFile(cacheFile, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0600); storeErr != nil { - return + // Finish writing before publishing the entry. Same-directory rename gives + // atomic replacement on Unix; it is best-effort on other platforms. + tmpCacheFile, err := os.CreateTemp(dir, ".gh-cache-*") + if err != nil { + return err } - + tmpCacheFileName := tmpCacheFile.Name() + // Clean up on errors and panics too. After a successful rename, the + // temporary path no longer exists, so removing it is harmless. defer func() { - if err := f.Close(); storeErr == nil && err != nil { - storeErr = err - } + _ = tmpCacheFile.Close() + _ = os.Remove(tmpCacheFileName) }() - var origBody io.ReadCloser - if res.Body != nil { - origBody, res.Body = copyStream(res.Body) - defer res.Body.Close() + if err := writeCacheResponse(tmpCacheFile, res); err != nil { + return err + } + if err := tmpCacheFile.Close(); err != nil { + return err } - storeErr = res.Write(f) - if origBody != nil { - res.Body = origBody + return renameCacheFile(tmpCacheFileName, cacheFilePath) +} + +func writeCacheResponse(w io.Writer, res *http.Response) error { + if res.Body == nil { + // Serialize the HTTP response headers only, since there is no body. + return res.Write(w) } - return + // Buffer the bytes consumed during serialization so the caller can replay + // them. Restore the replay reader even if writing fails or panics. + buffer := &bytes.Buffer{} + recorder := &errorRecordingReader{Reader: io.TeeReader(res.Body, buffer)} + source := &readCloser{Reader: recorder, Closer: res.Body} + res.Body = source + defer source.Close() + defer func() { + res.Body = io.NopCloser(&errorReplayingReader{Reader: buffer, err: recorder.err}) + }() + + return res.Write(w) +} + +type errorRecordingReader struct { + io.Reader + err error +} + +func (r *errorRecordingReader) Read(p []byte) (int, error) { + n, err := r.Reader.Read(p) + if err != nil && err != io.EOF { + r.err = err + } + return n, err +} + +type errorReplayingReader struct { + io.Reader + err error +} + +func (r *errorReplayingReader) Read(p []byte) (int, error) { + n, err := r.Reader.Read(p) + if err == io.EOF && r.err != nil { + err = r.err + r.err = nil + } + return n, err } -func copyStream(r io.ReadCloser) (io.ReadCloser, io.ReadCloser) { - b := &bytes.Buffer{} - nr := io.TeeReader(r, b) - return io.NopCloser(b), &readCloser{ - Reader: nr, - Closer: r, +func copyStream(body io.ReadCloser) (replay, source io.ReadCloser) { + buffer := &bytes.Buffer{} + return io.NopCloser(buffer), &readCloser{ + Reader: io.TeeReader(body, buffer), + Closer: body, } } diff --git a/pkg/api/cache_rename_other.go b/pkg/api/cache_rename_other.go new file mode 100644 index 0000000..d74dfb6 --- /dev/null +++ b/pkg/api/cache_rename_other.go @@ -0,0 +1,9 @@ +//go:build !windows + +package api + +import "os" + +func renameCacheFile(oldPath, newPath string) error { + return os.Rename(oldPath, newPath) +} diff --git a/pkg/api/cache_rename_windows.go b/pkg/api/cache_rename_windows.go new file mode 100644 index 0000000..6a002cb --- /dev/null +++ b/pkg/api/cache_rename_windows.go @@ -0,0 +1,45 @@ +package api + +import ( + "errors" + "os" + "time" + + "golang.org/x/sys/windows" +) + +func renameCacheFile(oldPath string, newPath string) error { + return retryCacheRename(func() (error, bool) { + err := os.Rename(oldPath, newPath) + return err, isRetryableCacheRenameError(err) + }) +} + +type retryableFn func() (err error, retryable bool) + +func retryCacheRename(rename retryableFn) error { + // Caching is best-effort: allow brief Windows sharing conflicts to clear + // without holding up an API response indefinitely. + deadline := time.Now().Add(100 * time.Millisecond) + for delay := time.Millisecond; ; delay *= 2 { + err, retryable := rename() + if err == nil { + return nil + } + + if !retryable { + return err + } + + remaining := time.Until(deadline) + if remaining <= 0 { + return err + } + time.Sleep(min(delay, remaining)) + } +} + +func isRetryableCacheRenameError(err error) bool { + return errors.Is(err, windows.ERROR_SHARING_VIOLATION) || + errors.Is(err, windows.ERROR_ACCESS_DENIED) +} diff --git a/pkg/api/cache_rename_windows_test.go b/pkg/api/cache_rename_windows_test.go new file mode 100644 index 0000000..f20f23f --- /dev/null +++ b/pkg/api/cache_rename_windows_test.go @@ -0,0 +1,94 @@ +package api + +import ( + "errors" + "os" + "path/filepath" + "testing" + "testing/synctest" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + "golang.org/x/sys/windows" +) + +func TestCacheRenameStopsRetryingAfterBudget(t *testing.T) { + t.Parallel() + + // Given a destination whose reader prevents replacement for the entire retry budget. + dir := t.TempDir() + oldPath, newPath := filepath.Join(dir, "temp"), filepath.Join(dir, "cache") + require.NoError(t, os.WriteFile(oldPath, []byte("replacement"), 0600)) + require.NoError(t, os.WriteFile(newPath, []byte("previous"), 0600)) + reader, err := os.Open(newPath) + require.NoError(t, err) + defer reader.Close() + + synctest.Test(t, func(t *testing.T) { + start := time.Now() + + // When publication is attempted while the reader remains open. + err := renameCacheFile(oldPath, newPath) + + // Then it returns the sharing error within budget + require.Error(t, err) + assert.True(t, errors.Is(err, windows.ERROR_SHARING_VIOLATION) || errors.Is(err, windows.ERROR_ACCESS_DENIED), + "expected a Windows sharing conflict, got %v", err) + elapsed := time.Since(start) + assert.Greater(t, elapsed, time.Duration(0), "expected retries before giving up") + assert.LessOrEqual(t, elapsed, 100*time.Millisecond, "cache retries must stay within the latency budget") + + // And the contents of both files are unchanged. + previous, err := os.ReadFile(newPath) + require.NoError(t, err) + assert.Equal(t, "previous", string(previous)) + replacement, err := os.ReadFile(oldPath) + require.NoError(t, err) + assert.Equal(t, "replacement", string(replacement)) + }) +} + +func TestCacheRenameWaitsForWindowsReader(t *testing.T) { + t.Parallel() + + // Given a destination held open without delete sharing by another reader. + dir := t.TempDir() + oldPath, newPath := filepath.Join(dir, "temp"), filepath.Join(dir, "cache") + require.NoError(t, os.WriteFile(oldPath, []byte("replacement"), 0600)) + require.NoError(t, os.WriteFile(newPath, []byte("previous"), 0600)) + reader, err := os.Open(newPath) + require.NoError(t, err) + defer reader.Close() + + synctest.Test(t, func(t *testing.T) { + // When the reader closes while the rename is waiting to retry. + done := make(chan error, 1) + go func() { done <- renameCacheFile(oldPath, newPath) }() + synctest.Wait() + require.NoError(t, reader.Close()) + + // Then the replacement succeeds. + require.NoError(t, <-done) + data, err := os.ReadFile(newPath) + require.NoError(t, err) + assert.Equal(t, "replacement", string(data)) + }) +} + +func TestCacheRenameReturnsMissingSourceImmediately(t *testing.T) { + t.Parallel() + + // Given a source file that does not exist. + dir := t.TempDir() + synctest.Test(t, func(t *testing.T) { + start := time.Now() + + // When it is renamed. + err := renameCacheFile(filepath.Join(dir, "missing"), filepath.Join(dir, "cache")) + + // Then the non-transient Windows error is returned without retrying. + require.ErrorIs(t, err, os.ErrNotExist) + assert.Zero(t, time.Since(start)) + }) +} diff --git a/pkg/api/cache_test.go b/pkg/api/cache_test.go index 5a1a89b..b2051ff 100644 --- a/pkg/api/cache_test.go +++ b/pkg/api/cache_test.go @@ -1,41 +1,45 @@ -package api +package api_test import ( "bytes" + "errors" "fmt" "io" "net/http" + "os" "path/filepath" + "strings" + "sync" "testing" "time" "github.com/cli/go-gh/v2/internal/testutils" + "github.com/cli/go-gh/v2/pkg/api" "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" ) func TestCacheResponse(t *testing.T) { testutils.StubConfig(t, "") counter := 0 - fakeHTTP := tripper{ - roundTrip: func(req *http.Request) (*http.Response, error) { - counter += 1 - body := fmt.Sprintf("%d: %s %s", counter, req.Method, req.URL.String()) - status := 200 - if req.URL.Path == "/error" { - status = 500 - } - return &http.Response{ - StatusCode: status, - Body: io.NopCloser(bytes.NewBufferString(body)), - }, nil - }, - } + fakeHTTP := cacheTestTransport(func(req *http.Request) (*http.Response, error) { + counter += 1 + body := fmt.Sprintf("%d: %s %s", counter, req.Method, req.URL.String()) + status := 200 + if req.URL.Path == "/error" { + status = 500 + } + return &http.Response{ + StatusCode: status, + Body: io.NopCloser(bytes.NewBufferString(body)), + }, nil + }) cacheDir := filepath.Join(t.TempDir(), "gh-cli-cache") - httpClient, err := NewHTTPClient( - ClientOptions{ + httpClient, err := api.NewHTTPClient( + api.ClientOptions{ Host: "github.com", AuthToken: "token", Transport: fakeHTTP, @@ -103,25 +107,23 @@ func TestCacheResponseRequestCacheOptions(t *testing.T) { testutils.StubConfig(t, "") counter := 0 - fakeHTTP := tripper{ - roundTrip: func(req *http.Request) (*http.Response, error) { - counter += 1 - body := fmt.Sprintf("%d: %s %s", counter, req.Method, req.URL.String()) - status := 200 - if req.URL.Path == "/error" { - status = 500 - } - return &http.Response{ - StatusCode: status, - Body: io.NopCloser(bytes.NewBufferString(body)), - }, nil - }, - } + fakeHTTP := cacheTestTransport(func(req *http.Request) (*http.Response, error) { + counter += 1 + body := fmt.Sprintf("%d: %s %s", counter, req.Method, req.URL.String()) + status := 200 + if req.URL.Path == "/error" { + status = 500 + } + return &http.Response{ + StatusCode: status, + Body: io.NopCloser(bytes.NewBufferString(body)), + }, nil + }) cacheDir := filepath.Join(t.TempDir(), "gh-cli-cache") - httpClient, err := NewHTTPClient( - ClientOptions{ + httpClient, err := api.NewHTTPClient( + api.ClientOptions{ Host: "github.com", AuthToken: "token", Transport: fakeHTTP, @@ -137,7 +139,6 @@ func TestCacheResponseRequestCacheOptions(t *testing.T) { if err != nil { return "", err } - req.Header.Set("X-GH-CACHE-DIR", cacheDir) req.Header.Set("X-GH-CACHE-TTL", "1h") res, err := httpClient.Do(req) if err != nil { @@ -187,12 +188,240 @@ func TestCacheResponseRequestCacheOptions(t *testing.T) { assert.Equal(t, "7: GET http://example.com/error", res) } -func TestRequestCacheOptions(t *testing.T) { - req, err := http.NewRequest("GET", "some/url", nil) - assert.NoError(t, err) - req.Header.Set("X-GH-CACHE-DIR", "some/dir/path") +func TestCacheRequestTTLOverridesClientTTL(t *testing.T) { + t.Parallel() + + // Given a cached response and a client whose default TTL treats it as expired. + dir := t.TempDir() + seed := cacheTestClient(t, dir, time.Hour, cacheTestResponse(strings.NewReader("cached response"))) + assert.Equal(t, "cached response", cacheTestFetch(t, seed)) + client := cacheTestClient(t, dir, -time.Second, cacheTestResponse(strings.NewReader("fresh response"))) + req, err := http.NewRequest("GET", "https://api.github.com/cache-test", nil) + require.NoError(t, err) req.Header.Set("X-GH-CACHE-TTL", "1h") - dir, ttl := requestCacheOptions(req) - assert.Equal(t, dir, "some/dir/path") - assert.Equal(t, ttl, time.Hour) + + // When a request specifies a longer TTL. + res, err := client.Do(req) + require.NoError(t, err) + defer res.Body.Close() + body, err := io.ReadAll(res.Body) + require.NoError(t, err) + + // Then that request uses the cache, but a request without the header refreshes it. + assert.Equal(t, "cached response", string(body)) + assert.Equal(t, "fresh response", cacheTestFetch(t, client)) +} + +func TestCachePublishesResponseWithoutBody(t *testing.T) { + t.Parallel() + + // Given a response with headers but no body. + dir := t.TempDir() + client := cacheTestClient(t, dir, time.Hour, cacheTestTransport(func(*http.Request) (*http.Response, error) { + return &http.Response{ + StatusCode: http.StatusNoContent, + Header: http.Header{"Etag": {`"v1"`}}, + }, nil + })) + res, err := client.Get("https://api.github.com/cache-test") + require.NoError(t, err) + require.NoError(t, res.Body.Close()) + reader := cacheTestClient(t, dir, time.Hour, cacheTestTransport(func(*http.Request) (*http.Response, error) { + return nil, errors.New("unexpected cache miss") + })) + + // When another client requests the cached response. + cached, err := reader.Get("https://api.github.com/cache-test") + require.NoError(t, err) + defer cached.Body.Close() + + // Then its status and headers are preserved, with an empty body. + assert.Equal(t, http.StatusNoContent, cached.StatusCode) + assert.Equal(t, `"v1"`, cached.Header.Get("Etag")) + body, err := io.ReadAll(cached.Body) + require.NoError(t, err) + assert.Empty(t, body) +} + +func TestCachePreservesEntryAfterFailedRefresh(t *testing.T) { + t.Parallel() + + // Given a cached response and a refresh whose body fails partway through. + dir := t.TempDir() + seed := cacheTestClient(t, dir, time.Hour, cacheTestResponse(strings.NewReader("previous response"))) + assert.Equal(t, "previous response", cacheTestFetch(t, seed)) + refresh := cacheTestClient(t, dir, -time.Second, cacheTestResponse(io.MultiReader( + strings.NewReader("incomplete response"), + cacheTestReader(func([]byte) (int, error) { return 0, io.ErrUnexpectedEOF }), + ))) + + // When writing the refresh fails. + res, err := refresh.Get("https://api.github.com/cache-test") + require.NoError(t, err) + body, err := io.ReadAll(res.Body) + assert.Equal(t, "incomplete response", string(body)) + require.ErrorIs(t, err, io.ErrUnexpectedEOF) + require.NoError(t, res.Body.Close()) + + // Then another client can still read the previous entry. + reader := cacheTestClient(t, dir, time.Hour, cacheTestTransport(func(*http.Request) (*http.Response, error) { + return nil, errors.New("unexpected cache miss") + })) + assert.Equal(t, "previous response", cacheTestFetch(t, reader)) +} + +func TestCachePublishesOnlyCompleteResponses(t *testing.T) { + t.Parallel() + + // Given independent clients sharing a cache and a refresh paused mid-body. + dir := t.TempDir() + seed := cacheTestClient(t, dir, time.Hour, cacheTestResponse(strings.NewReader("previous response"))) + assert.Equal(t, "previous response", cacheTestFetch(t, seed)) + body, writer := io.Pipe() + refresh := cacheTestClient(t, dir, -time.Second, cacheTestResponse(body)) + reader := cacheTestClient(t, dir, time.Hour, cacheTestTransport(func(*http.Request) (*http.Response, error) { + return nil, errors.New("unexpected cache miss") + })) + var ( + workers sync.WaitGroup + refreshErr error + ) + t.Cleanup(func() { + _ = writer.Close() + _ = body.Close() + workers.Wait() + }) + + // When another client reads while the refresh is still being written. + workers.Go(func() { + defer body.Close() + // This refresh is reading from the pipe, simulating a response body that is being written concurrently. + // Since the pipe will need to EOF, the refresh will block until the writer is closed. + res, err := refresh.Get("https://api.github.com/cache-test") + if err == nil { + err = res.Body.Close() + } + refreshErr = err + }) + _, err := io.WriteString(writer, "replacement ") + require.NoError(t, err) + // At this point, the refresh has not finished writing, so the reader should still see the previous response. + assert.Equal(t, "previous response", cacheTestFetch(t, reader)) + + // Finish the replacement and wait for publication. + _, err = io.WriteString(writer, "complete") + require.NoError(t, err) + require.NoError(t, writer.Close()) + workers.Wait() + require.NoError(t, refreshErr) + + // Then readers see the complete replacement. + assert.Equal(t, "replacement complete", cacheTestFetch(t, reader)) +} + +func TestCacheCleansUpAfterBodyPanic(t *testing.T) { + t.Parallel() + + // Given a response body that panics while being cached. + dir := t.TempDir() + client := cacheTestClient(t, dir, time.Hour, cacheTestTransport(func(*http.Request) (*http.Response, error) { + return &http.Response{ + StatusCode: http.StatusOK, + Body: io.NopCloser(cacheTestReader(func([]byte) (int, error) { + panic("body read failed") + })), + }, nil + })) + + // When the panic propagates to the caller. + assert.PanicsWithValue(t, "body read failed", func() { + _, _ = client.Get("https://api.github.com/cache-test") + }) + + // Then no partial cache entry or temporary file remains. + assert.Empty(t, cacheTestFiles(t, dir)) +} + +func TestCachePublicationFailureDoesNotFailResponse(t *testing.T) { + t.Parallel() + + // Given a cache destination that cannot be replaced by a file. + dir := t.TempDir() + seed := cacheTestClient(t, dir, time.Hour, cacheTestResponse(strings.NewReader("previous response"))) + assert.Equal(t, "previous response", cacheTestFetch(t, seed)) + files := cacheTestFiles(t, dir) + require.Len(t, files, 1) + require.NoError(t, os.Remove(files[0])) + require.NoError(t, os.Mkdir(files[0], 0700)) + client := cacheTestClient(t, dir, time.Hour, cacheTestResponse(strings.NewReader("fresh response"))) + + // When the HTTP request succeeds but cache publication fails. + body := cacheTestFetch(t, client) + + // Then the caller still receives the response and no temporary file leaks. + assert.Equal(t, "fresh response", body) + assert.Empty(t, cacheTestFiles(t, dir)) +} + +func cacheTestClient(t *testing.T, dir string, ttl time.Duration, transport http.RoundTripper) *http.Client { + t.Helper() + client, err := api.NewHTTPClient(api.ClientOptions{ + Host: "github.com", + APIHost: "api.github.com", + AuthToken: "token", + CacheDir: dir, + CacheTTL: ttl, + EnableCache: true, + LogIgnoreEnv: true, + Transport: transport, + }) + require.NoError(t, err) + return client +} + +func cacheTestFiles(t *testing.T, dir string) []string { + t.Helper() + var files []string + err := filepath.WalkDir(dir, func(path string, entry os.DirEntry, err error) error { + if err != nil { + return err + } + if !entry.IsDir() { + files = append(files, path) + } + return nil + }) + require.NoError(t, err) + return files +} + +func cacheTestResponse(body io.Reader) http.RoundTripper { + return cacheTestTransport(func(*http.Request) (*http.Response, error) { + return &http.Response{ + StatusCode: http.StatusOK, + Body: io.NopCloser(body), + }, nil + }) +} + +func cacheTestFetch(t *testing.T, client *http.Client) string { + t.Helper() + res, err := client.Get("https://api.github.com/cache-test") + require.NoError(t, err) + defer res.Body.Close() + body, err := io.ReadAll(res.Body) + require.NoError(t, err) + return string(body) +} + +type cacheTestTransport func(*http.Request) (*http.Response, error) + +func (f cacheTestTransport) RoundTrip(req *http.Request) (*http.Response, error) { + return f(req) +} + +type cacheTestReader func([]byte) (int, error) + +func (f cacheTestReader) Read(p []byte) (int, error) { + return f(p) }