Merge pull request #371 from rest-sh/fix/local-spec-startup-cache

fix: speed up local spec startup

Author: danielgtaylor

internal/cli/cli.go

@@ -778,6 +778,7 @@ type cliArgScan struct {
 	ProfileName             string
 	ConfigPath              string
 	ExplicitConfigPath      bool
+	VersionFlag             bool
 	Silent                  bool
 	Bootstrap               bool
 	GeneratedAPICommandTree bool
@@ -793,11 +794,16 @@ func scanCLIArgs(args []string) cliArgScan {
 		return scan
 	}
 
+	hasHelpFlag := false
 	hasBootstrapFlag := false
 	for i := 1; i < len(args); i++ {
 		arg := args[i]
 		switch arg {
-		case "--help", "-h", "--version":
+		case "--help", "-h":
+			hasHelpFlag = true
+			hasBootstrapFlag = true
+		case "--version":
+			scan.VersionFlag = true
 			hasBootstrapFlag = true
 		case "--rsh-silent", "-S":
 			scan.Silent = true
@@ -865,6 +871,8 @@ func scanCLIArgs(args []string) cliArgScan {
 	}
 	if hasBootstrapFlag {
 		scan.Bootstrap = true
+	}
+	if hasHelpFlag {
 		scan.GeneratedAPICommandTree = true
 	}
 	return scan
@@ -1137,6 +1145,9 @@ func quietGeneratedWarningsForScan(scan cliArgScan, cfg *config.Config) bool {
 }
 
 func (c *CLI) generatedAPINamesForScan(scan cliArgScan, cfg *config.Config) []string {
+	if scan.VersionFlag {
+		return nil
+	}
 	if scan.GeneratedAPICommandTree {
 		if scan.FirstCommand != "" && !isBuiltinCommandName(scan.FirstCommand) {
 			if _, ok := cfg.APIs[scan.FirstCommand]; ok {

internal/cli/cli_internal_test.go

@@ -321,3 +321,29 @@ func TestQuietGeneratedWarningsForScan(t *testing.T) {
 		})
 	}
 }
+
+func TestScanVersionDoesNotRequestGeneratedAPICommandTree(t *testing.T) {
+	cfg := &config.Config{
+		APIs: map[string]*config.APIConfig{
+			"myapi": {BaseURL: "https://api.example.com"},
+		},
+	}
+	scan := scanCLIArgs([]string{"restish", "--version"})
+	if !scan.Bootstrap {
+		t.Fatal("--version should remain a bootstrap command")
+	}
+	if scan.GeneratedAPICommandTree {
+		t.Fatal("--version should not load generated API command metadata")
+	}
+	if got := (&CLI{}).generatedAPINamesForScan(scan, cfg); len(got) != 0 {
+		t.Fatalf("--version generated APIs = %v, want none", got)
+	}
+
+	helpScan := scanCLIArgs([]string{"restish", "--help"})
+	if !helpScan.GeneratedAPICommandTree {
+		t.Fatal("--help should still include generated API commands")
+	}
+	if got := (&CLI{}).generatedAPINamesForScan(helpScan, cfg); !reflect.DeepEqual(got, []string{"myapi"}) {
+		t.Fatalf("--help generated APIs = %v, want [myapi]", got)
+	}
+}

internal/spec/cache.go

@@ -31,12 +31,13 @@ type cacheEntry struct {
 }
 
 type cachedSpecFile struct {
-	Source  string    `cbor:"source"`
-	Local   bool      `cbor:"local,omitempty"`
-	Path    string    `cbor:"path,omitempty"`
-	ModTime time.Time `cbor:"mod_time,omitempty"`
-	Size    int64     `cbor:"size,omitempty"`
-	SHA256  string    `cbor:"sha256,omitempty"`
+	Source          string    `cbor:"source"`
+	Local           bool      `cbor:"local,omitempty"`
+	Path            string    `cbor:"path,omitempty"`
+	ModTime         time.Time `cbor:"mod_time,omitempty"`
+	ModTimeUnixNano int64     `cbor:"mod_time_unix_nano,omitempty"`
+	Size            int64     `cbor:"size,omitempty"`
+	SHA256          string    `cbor:"sha256,omitempty"`
 }
 
 type cachedRaw struct {

internal/spec/cache_test.go

@@ -389,6 +389,111 @@ func TestLoadOperationsFromCache(t *testing.T) {
 	}
 }
 
+func TestLoadOperationSetFromCacheAcceptsLegacyLocalSpecFileSecondPrecisionModTime(t *testing.T) {
+	dir := t.TempDir()
+	specPath := filepath.Join(dir, "spec.yaml")
+	raw := []byte(`{"openapi":"3.1.0","info":{"title":"Test","version":"1.0.0"},"paths":{"/items":{"get":{"operationId":"listItems","responses":{"200":{"description":"OK"}}}}}}`)
+	if err := os.WriteFile(specPath, raw, 0o600); err != nil {
+		t.Fatalf("write spec: %v", err)
+	}
+	mtime := time.Unix(1700000000, 987654321)
+	if err := os.Chtimes(specPath, mtime, mtime); err != nil {
+		t.Fatalf("chtimes: %v", err)
+	}
+	info, err := os.Stat(specPath)
+	if err != nil {
+		t.Fatalf("stat spec: %v", err)
+	}
+	if info.ModTime().Nanosecond() == 0 {
+		t.Skip("filesystem does not preserve subsecond mtimes")
+	}
+	loaded, err := load("application/json", raw, DefaultLoaders())
+	if err != nil {
+		t.Fatalf("load: %v", err)
+	}
+	set, err := loaded.OperationSet(OperationOptions{})
+	if err != nil {
+		t.Fatalf("operation set: %v", err)
+	}
+
+	entry := &cacheEntry{
+		Version:   "v2",
+		FetchedAt: info.ModTime().Add(time.Minute),
+		ExpiresAt: time.Now().Add(time.Hour),
+		Spec: cachedRaw{
+			ContentType: "application/json",
+			Raw:         raw,
+			LocalPath:   specPath,
+		},
+		SpecFiles: []cachedSpecFile{{
+			Source:  specPath,
+			Local:   true,
+			Path:    specPath,
+			ModTime: info.ModTime().Truncate(time.Second),
+			Size:    info.Size(),
+		}},
+	}
+	entry.upsertOperationSet(OperationOptions{}, set)
+	if err := writeCache(dir, "testapi", entry); err != nil {
+		t.Fatalf("writeCache: %v", err)
+	}
+
+	got, _, ok := LoadOperationSetFromCacheStatus(dir, "testapi", "v2", []string{specPath}, OperationOptions{}, true)
+	if !ok {
+		t.Fatal("expected operations cache hit")
+	}
+	if len(got.Operations) != 1 || got.Operations[0].ID != "listItems" {
+		t.Fatalf("unexpected operations: %#v", got.Operations)
+	}
+}
+
+func TestStoreSpecInCachePreservesLocalSpecFileNanosecondModTime(t *testing.T) {
+	dir := t.TempDir()
+	specPath := filepath.Join(dir, "spec.yaml")
+	raw := []byte(`{"openapi":"3.1.0","info":{"title":"Test","version":"1.0.0"},"paths":{"/items":{"get":{"operationId":"listItems","responses":{"200":{"description":"OK"}}}}}}`)
+	if err := os.WriteFile(specPath, raw, 0o600); err != nil {
+		t.Fatalf("write spec: %v", err)
+	}
+	mtime := time.Unix(1700000000, 456789123)
+	if err := os.Chtimes(specPath, mtime, mtime); err != nil {
+		t.Fatalf("chtimes: %v", err)
+	}
+	info, err := os.Stat(specPath)
+	if err != nil {
+		t.Fatalf("stat spec: %v", err)
+	}
+	if info.ModTime().Nanosecond() == 0 {
+		t.Skip("filesystem does not preserve subsecond mtimes")
+	}
+	apiSpec, err := OpenAPILoader{}.Load(raw)
+	if err != nil {
+		t.Fatalf("load: %v", err)
+	}
+
+	if err := StoreSpecInCache(dir, "testapi", "v2", apiSpec, []string{specPath}, OperationOptions{}, time.Hour); err != nil {
+		t.Fatalf("StoreSpecInCache: %v", err)
+	}
+
+	entry, ok := readCacheEntry(dir, "testapi", "v2", true)
+	if !ok {
+		t.Fatal("expected cache entry")
+	}
+	if len(entry.SpecFiles) != 1 {
+		t.Fatalf("SpecFiles len = %d, want 1", len(entry.SpecFiles))
+	}
+	if got, want := entry.SpecFiles[0].ModTimeUnixNano, info.ModTime().UnixNano(); got != want {
+		t.Fatalf("cached ModTimeUnixNano = %d, want %d", got, want)
+	}
+
+	got, _, ok := LoadOperationSetFromCacheStatus(dir, "testapi", "v2", []string{specPath}, OperationOptions{}, true)
+	if !ok {
+		t.Fatal("expected operations cache hit")
+	}
+	if len(got.Operations) != 1 || got.Operations[0].ID != "listItems" {
+		t.Fatalf("unexpected operations: %#v", got.Operations)
+	}
+}
+
 func TestLoadOperationSetFromCacheStatusAllowsStaleRemoteMetadata(t *testing.T) {
 	dir := t.TempDir()
 	raw := []byte(`{"openapi":"3.1.0","info":{"title":"Test","version":"1.0.0"},"paths":{"/items":{"get":{"operationId":"listItems","responses":{"200":{"description":"OK"}}}}}}`)

internal/spec/discover.go

@@ -282,6 +282,7 @@ func cacheSpecFileMetadata(specFiles []string) []cachedSpecFile {
 				meta.Path = path
 				if info, statErr := os.Stat(path); statErr == nil {
 					meta.ModTime = info.ModTime()
+					meta.ModTimeUnixNano = info.ModTime().UnixNano()
 					meta.Size = info.Size()
 				}
 			}
@@ -305,13 +306,27 @@ func cacheSpecFileMetadataMatches(specFiles []string, cached []cachedSpecFile) b
 			current[i].Size != cached[i].Size {
 			return false
 		}
-		if current[i].Local && !current[i].ModTime.Equal(cached[i].ModTime) {
+		if current[i].Local && !cachedSpecFileModTimeMatches(current[i], cached[i]) {
 			return false
 		}
 	}
 	return true
 }
 
+func cachedSpecFileModTimeMatches(current, cached cachedSpecFile) bool {
+	if current.ModTimeUnixNano != 0 && cached.ModTimeUnixNano != 0 {
+		return current.ModTimeUnixNano == cached.ModTimeUnixNano
+	}
+	if current.ModTime.Equal(cached.ModTime) {
+		return true
+	}
+	// Legacy cache entries stored time.Time values that could round-trip
+	// through CBOR at whole-second precision. Keep those caches usable when the
+	// path, size, and second-level mtime still match; specFilesChangedSince
+	// separately rejects local files modified after the cache was written.
+	return current.ModTime.Truncate(time.Second).Equal(cached.ModTime.Truncate(time.Second))
+}
+
 func specFilesChangedSince(specFiles []string, fetchedAt time.Time) bool {
 	if fetchedAt.IsZero() {
 		return false

internal/spec/discover_test.go

@@ -399,7 +399,7 @@ func TestCacheSpecFileMetadataAvoidsContentHash(t *testing.T) {
 	if len(meta) != 1 {
 		t.Fatalf("metadata len = %d, want 1", len(meta))
 	}
-	if meta[0].Size == 0 || meta[0].ModTime.IsZero() {
+	if meta[0].Size == 0 || meta[0].ModTime.IsZero() || meta[0].ModTimeUnixNano == 0 {
 		t.Fatalf("expected size and mtime metadata, got %+v", meta[0])
 	}
 	if meta[0].SHA256 != "" {
@@ -410,6 +410,36 @@ func TestCacheSpecFileMetadataAvoidsContentHash(t *testing.T) {
 	}
 }
 
+func TestCacheSpecFileMetadataMatchesLegacySecondPrecisionModTime(t *testing.T) {
+	dir := t.TempDir()
+	specPath := filepath.Join(dir, "spec.yaml")
+	if err := os.WriteFile(specPath, []byte("openapi: 3.1.0\ninfo: {title: Demo, version: v1}\npaths: {}\n"), 0o600); err != nil {
+		t.Fatalf("write spec: %v", err)
+	}
+	mtime := time.Unix(1700000000, 123456789)
+	if err := os.Chtimes(specPath, mtime, mtime); err != nil {
+		t.Fatalf("chtimes: %v", err)
+	}
+	info, err := os.Stat(specPath)
+	if err != nil {
+		t.Fatalf("stat spec: %v", err)
+	}
+	if info.ModTime().Nanosecond() == 0 {
+		t.Skip("filesystem does not preserve subsecond mtimes")
+	}
+
+	legacy := []cachedSpecFile{{
+		Source:  specPath,
+		Local:   true,
+		Path:    specPath,
+		ModTime: info.ModTime().Truncate(time.Second),
+		Size:    info.Size(),
+	}}
+	if !cacheSpecFileMetadataMatches([]string{specPath}, legacy) {
+		t.Fatal("legacy whole-second mtime metadata should match unchanged file")
+	}
+}
+
 // ---- loadSpecFiles -------------------------------------------------------
 
 func TestLoadSpecFiles_LocalFile(t *testing.T) {