Fix codespace state refresh and improve setup flow #214
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…ements - Worker-side verification caching with 60s TTL and 10s rate limiting - iOS reconnect flow with forceRefresh parameter - SSE setup event enrichment with next_action routing - Create repository guidance screen for zero-repo users 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Prevent worktree contents from being tracked in repository. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Comprehensive plan with 11 tasks broken into bite-sized steps: Worker tasks (1-4): - Add verification cache infrastructure to Durable Object - Implement cache storage routes - Add caching and rate limiting to /v1/user/status - Enhance SSE setup event with next_action routing iOS tasks (5-9): - Update SSEEvent enum with nextAction parameter - Add rate limiting to CatnipInstaller - Create repository guidance screen for zero-repo users - Route setup events based on worker next_action - Update WorkspacesView reconnect flow Testing and deployment (10-11): - Manual testing verification - Deploy and monitor Each task follows TDD with explicit test/verify steps. Ref: docs/plans/2025-11-07-codespace-state-refresh-design.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Add VerificationCache interface and helper functions to support rate-limited codespace verification with GitHub API. - Cache tracks lastVerified (60s TTL) and lastRefreshRequest (10s rate limit) - Helper functions for get/update operations - Foundation for /v1/user/status caching logic Ref: docs/plans/2025-11-07-codespace-state-refresh-design.md
Add GET and PATCH routes for verification-cache storage:
- GET /verification-cache/{username} - retrieve cache
- PATCH /verification-cache/{username} - update cache fields
Cache stored in Durable Object state with key pattern
'verification-cache:{username}' for per-user isolation.
Ref: docs/plans/2025-11-07-codespace-state-refresh-design.md
- Add try-catch for JSON parsing in PATCH handler (return 400 on error) - Add 405 handler for unsupported HTTP methods - Changes GET/PATCH from separate if blocks to if/else if/else chain Addresses code review feedback from Task 2 review. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Implement verification cache with dual-layer protection: - 60-second cache TTL for normal requests (reduces GitHub API calls) - 10-second rate limiting on ?refresh=true (prevents abuse) - Server-side enforcement protects quota even if client has bugs Rate limiting behavior: - If refresh requested < 10s after last refresh, log warning and use cache - If cache older than 60s, automatically verify even without refresh param - Graceful degradation serves cached data when rate limited Ref: docs/plans/2025-11-07-codespace-state-refresh-design.md
- Add nested try-catch for verification logic (graceful degradation on error) - Add null safety check when accessing cached codespace data - Fall back to cached data or false when verification fails Addresses code review feedback from Task 3.
Worker now determines appropriate next_action based on user's GitHub state: - 'create_repo' if user has zero repositories - 'install' if user has repositories (default flow) - 'launch' reserved for future use (when we detect Catnip repos) Setup event now includes: - message: User-facing message - next_action: Routing hint for iOS (install/launch/create_repo) - total_repositories: Count of writable repos This centralizes decision logic in worker, simplifying iOS routing. Ref: docs/plans/2025-11-07-codespace-state-refresh-design.md
Remove repositories_with_catnip field from zero-repo setup event for consistency. iOS will determine Catnip feature status separately. Addresses code review feedback from Task 4. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Update SSEEvent enum to include nextAction routing hint from worker: - SSEEvent.setup now includes nextAction string parameter - Parse next_action field from SSE JSON data - Default to 'install' if field missing (backward compatibility) Enables iOS to route based on worker's determination of user state. Ref: docs/plans/2025-11-07-codespace-state-refresh-design.md
Implement dual-layer rate limiting protection: - Track lastRefreshTime to prevent calls within 10 seconds - Add forceRefresh parameter to explicitly request verification - Fail fast on client to avoid unnecessary network calls - Server also enforces same limit as backup Rate limiting behavior: - If forceRefresh called < 10s after last, log and return early - Track timestamp BEFORE call to prevent race conditions - Clear logging for debugging reconnect flows Ref: docs/plans/2025-11-07-codespace-state-refresh-design.md
Add friendly onboarding flow for users with zero repositories: - New createRepository phase in CodespacePhase enum - Welcoming screen with clear call-to-action - Direct link to GitHub new repo page - Self-service 'I Created a Repository' button to refresh and advance - Graceful error handling if still no repos after refresh Replaces technical Setup view for zero-repo users with approachable first-time experience. Ref: docs/plans/2025-11-07-codespace-state-refresh-design.md
Update handleSSEEvent to route based on worker's next_action: - 'create_repo' → createRepository phase (friendly onboarding) - 'install' → repositorySelection with installation mode - 'launch' → repositorySelection with launch mode - unknown → fallback to old setup view (backward compatibility) Worker now centralizes decision logic based on GitHub state, iOS just follows routing instructions. Clear logging for debugging routing decisions. Ref: docs/plans/2025-11-07-codespace-state-refresh-design.md
Update reconnect flow to fetch fresh user status before navigating: - Call fetchUserStatus(forceRefresh: true) on reconnect button press - Triggers worker verification with GitHub API (rate-limited) - Navigate to CodespaceView only after state refreshes - Graceful degradation if refresh fails Ensures CodespaceView sees fresh has_any_codespaces flag, preventing stale 'Access My Codespace' button after deletion. Ref: docs/plans/2025-11-07-codespace-state-refresh-design.md
Remove implementation plan documents from version control: - Remove docs/plans/2025-11-07-codespace-state-refresh-design.md - Remove docs/plans/2025-11-07-codespace-state-refresh.md - Add docs/plans/ to .gitignore These planning documents are kept locally for reference but not tracked in git as they're specific to development workflow.
Fix TypeScript compilation errors: - Use optional chaining for verifiedCodespaces.length access - Properly handle null/undefined with parentheses and ?? operator - Change from 'cache?.verifiedCodespaces.length > 0 ?? false' to '(cache?.verifiedCodespaces?.length ?? 0) > 0' Resolves TS18048 and TS2870 type errors.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Fixes two critical UX issues in the Catnip iOS app:
Issue 1: Stale codespace state after deletion
Issue 2: Confusing Setup flow
Architecture
Worker Side:
/v1/user/statusto reduce GitHub API calls?refresh=truerequests (dual-layer: client + server)next_actionfield based on GitHub repository stateiOS Side:
fetchUserStatus(forceRefresh: true)on reconnect to get fresh statenext_actiondeterminationTest Plan
Implementation Details
Worker Changes (Tasks 1-4)
VerificationCacheinterface and helpers for Durable Object storage/verification-cache/{username})/v1/user/statuswith caching and rate limitingiOS Changes (Tasks 5-9)
SSEEvent.setupto includenextActionparameterCatnipInstaller.fetchUserStatuscreateRepositoryphase and view for zero-repo usershandleSSEEventto route based onnext_actionWorkspacesViewreconnect flow to refresh state before navigationReferences
docs/plans/2025-11-07-codespace-state-refresh-design.mddocs/plans/2025-11-07-codespace-state-refresh.md🤖 Generated with Claude Code