Add cache expiration and flush endpoint to TypeScript server

- Add TTL-based expiration to LRU cache entries (24h for found, 60s for not found)
- Implement /flush-cache POST endpoint to manually clear cache
- Update cache to check expiration on retrieval and refetch stale entries
- Update README with version parameter docs and new endpoint

This improves cache behavior by allowing quick refresh of "not found" entries
while keeping successful lookups cached longer for performance.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: zshannon

server/README.md

@@ -7,8 +7,8 @@ A high-performance HTTP server that provides TypeScript type checking and JavaSc
 - **TypeScript type checking**: Full TypeScript type checking with detailed diagnostics
 - **JavaScript bundling**: Uses esbuild for fast, optimized JavaScript output
 - **React support**: Built-in React global transform for JSX
-- **In-memory compilation**: No file system I/O required
-- **Module caching**: Node modules loaded once at startup for fast performance
+- **S3-backed module system**: Node modules and type definitions loaded from S3
+- **LRU caching**: In-memory cache for S3 content with configurable size
 - **High performance**: ~155ms average build time, ~208ms typecheck (including network latency)
 
 ## API
@@ -30,13 +30,8 @@ Returns server health and statistics.
   "status": "healthy",
   "version": "1.0.0",
   "uptime": "26s",
-  "modules": {
-    "TotalFiles": 2557,
-    "TypeDefinitions": 482,
-    "JavaScriptFiles": 2056,
-    "PackageFiles": 19,
-    "LoadErrors": 0
-  }
+  "cache_size": "32 MB",
+  "cache_entries": 150
 }
 ```
 
@@ -46,7 +41,8 @@ Type checks TypeScript code without compilation.
 **Request:**
 ```json
 {
-  "code": "export const hello: string = 123"
+  "code": "export const hello: string = 123",
+  "version": "0.0.1"
 }
 ```
 
@@ -79,7 +75,8 @@ Compiles and bundles TypeScript code to JavaScript.
 **Request:**
 ```json
 {
-  "code": "export const hello: string = \"world\""
+  "code": "export const hello: string = \"world\"",
+  "version": "0.0.1"
 }
 ```
 
@@ -118,6 +115,24 @@ If type errors are found, returns them without attempting to build:
 }
 ```
 
+### `POST /flush-cache`
+Flushes the in-memory LRU cache for S3 content.
+
+**Request:**
+```
+POST /flush-cache
+```
+
+**Response:**
+```json
+{
+  "status": "success",
+  "message": "Cache flushed successfully",
+  "entries_cleared": 150,
+  "timestamp": 1702934567
+}
+```
+
 ## Deployment
 
 ### Fly.io

server/server.go

@@ -43,14 +43,19 @@ var (
 
 	// Cache configuration
 	cacheSize   int64
+	
+	// Cache TTL settings
+	cacheTTLSuccess   = 24 * time.Hour   // TTL for found entries
+	cacheTTLNotFound  = 60 * time.Second // TTL for not found entries
 )
 
 type CacheEntry struct {
-	Exists   bool     // false if not found in S3
-	IsFile   bool     // true for file, false for directory
-	Content  []byte   // file content (only for files)
-	Files    []string // immediate child files (only for dirs)
-	Dirs     []string // immediate child dirs (only for dirs)
+	Exists    bool      // false if not found in S3
+	IsFile    bool      // true for file, false for directory
+	Content   []byte    // file content (only for files)
+	Files     []string  // immediate child files (only for dirs)
+	Dirs      []string  // immediate child dirs (only for dirs)
+	ExpiresAt time.Time // expiration time for this entry
 }
 
 type TypecheckRequest struct {
@@ -115,11 +120,21 @@ func getFromCache(ctx context.Context, version, path string) *CacheEntry {
 	// Check cache first
 	cacheMutex.RLock()
 	if cached, ok := cache.Get(cacheKey); ok {
+		// Check if entry has expired
+		if time.Now().Before(cached.ExpiresAt) {
+			cacheMutex.RUnlock()
+			s3CacheHits.Inc()
+			return cached
+		}
+		// Entry expired, will refetch
+		cacheMutex.RUnlock()
+		// Remove expired entry
+		cacheMutex.Lock()
+		cache.Remove(cacheKey)
+		cacheMutex.Unlock()
+	} else {
 		cacheMutex.RUnlock()
-		s3CacheHits.Inc()
-		return cached
 	}
-	cacheMutex.RUnlock()
 
 	s3CacheMisses.Inc()
 
@@ -137,9 +152,10 @@ func getFromCache(ctx context.Context, version, path string) *CacheEntry {
 		if err == nil {
 			// log.Printf("S3 file found: %s (%d bytes)", cacheKey, len(content))
 			entry := &CacheEntry{
-				Exists:  true,
-				IsFile:  true,
-				Content: content,
+				Exists:    true,
+				IsFile:    true,
+				Content:   content,
+				ExpiresAt: time.Now().Add(cacheTTLSuccess),
 			}
 			cacheMutex.Lock()
 			cache.Add(cacheKey, entry)
@@ -169,8 +185,11 @@ func getFromCache(ctx context.Context, version, path string) *CacheEntry {
 	if err != nil {
 		s3ListErrors.Inc()
 		// log.Printf("S3 list error for key %s: %v", cacheKey, err)
-		// Cache as non-existent
-		entry := &CacheEntry{Exists: false}
+		// Cache as non-existent with shorter TTL
+		entry := &CacheEntry{
+			Exists:    false,
+			ExpiresAt: time.Now().Add(cacheTTLNotFound),
+		}
 		cacheMutex.Lock()
 		cache.Add(cacheKey, entry)
 		cacheMutex.Unlock()
@@ -208,6 +227,13 @@ func getFromCache(ctx context.Context, version, path string) *CacheEntry {
 		}
 	}
 
+	// Set expiration based on whether entry was found
+	if entry.Exists {
+		entry.ExpiresAt = time.Now().Add(cacheTTLSuccess)
+	} else {
+		entry.ExpiresAt = time.Now().Add(cacheTTLNotFound)
+	}
+	
 	// Cache the result
 	cacheMutex.Lock()
 	cache.Add(cacheKey, entry)
@@ -829,6 +855,39 @@ func build(w http.ResponseWriter, req *http.Request) {
 	json.NewEncoder(w).Encode(response)
 }
 
+func flushCache(w http.ResponseWriter, req *http.Request) {
+	if req.Method != http.MethodPost {
+		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+
+	// Get cache metrics before flush
+	var entriesBefore int
+	cacheMutex.RLock()
+	if cache != nil {
+		entriesBefore = cache.Len()
+	}
+	cacheMutex.RUnlock()
+
+	// Flush the cache
+	cacheMutex.Lock()
+	if cache != nil {
+		cache.Purge()
+	}
+	cacheMutex.Unlock()
+
+	// Return flush summary
+	response := map[string]interface{}{
+		"status":          "success",
+		"message":         "Cache flushed successfully",
+		"entries_cleared": entriesBefore,
+		"timestamp":       time.Now().Unix(),
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(response)
+}
+
 func main() {
 	log.Printf("TypeScript Go Server v%s starting...", serverVersion)
 
@@ -883,13 +942,14 @@ func main() {
 	http.HandleFunc("/health", loggingMiddleware(health))
 	http.HandleFunc("/typecheck", loggingMiddleware(typecheck))
 	http.HandleFunc("/build", loggingMiddleware(build))
+	http.HandleFunc("/flush-cache", loggingMiddleware(flushCache))
 	http.HandleFunc("/", loggingMiddleware(hello))
 
 	// Start Prometheus metrics server on port 9091
 	go startMetricsServer()
 
 	log.Printf("Server ready! Listening on :8080...")
-	log.Printf("Endpoints: /, /health, /typecheck, /build")
+	log.Printf("Endpoints: /, /health, /typecheck, /build, /flush-cache")
 	log.Printf("Metrics available at :9091/metrics")
 
 	if err := http.ListenAndServe(":8080", nil); err != nil {