[ardabot] SDK changes for upstash/qstash-server#884

[CahidArda]

Automated SDK Update

This PR was automatically generated by ardabot based on changes in upstash/qstash-server#884.

Server Change Summary

I've read the task file. This is an analysis task for a server-side PR. Let me analyze the diff and provide the structured summary as requested.

Based on the diff provided, here's my analysis:

Changes Summary

• Added a new /v2/readiness endpoint to check the readiness state of the QStash service
• The endpoint follows the same pattern as the existing /v2/liveness endpoint

New APIs/Endpoints

• GET /v2/readiness
  • Parameters: None
  • Returns: HTTP 200 status with "OK" string response
  • Purpose: Health check endpoint to determine if the service is ready to accept requests

Modified APIs/Endpoints

• None

Breaking Changes

• None

Notes for SDK Implementors

• This is a new health check endpoint that complements the existing /v2/liveness endpoint
• The readiness endpoint is commonly used in orchestration systems (like Kubernetes) to determine when a service is ready to receive traffic
• SDK clients may want to expose a readiness() or checkReadiness() method similar to any existing liveness check methods
• The endpoint requires no authentication or special headers based on the implementation
• Returns a simple "OK" string with HTTP 200 status on success
• This is an optional convenience endpoint - SDK implementors can choose whether to expose it based on their client use cases

SDK Change Plan

Now I'll create a detailed, language-agnostic plan for updating SDK clients based on the server-side readiness endpoint addition.

Based on the task file, I need to create a detailed plan for updating SDK clients to support the new /v2/readiness endpoint. Let me provide a comprehensive, language-agnostic implementation plan.

---

SDK Client Implementation Plan for Readiness Endpoint

1. New Methods/Functions to Add

Primary Method

readiness() -> ReadinessResponse

• Purpose: Check if the QStash service is ready to accept requests
• HTTP Method: GET
• Endpoint: /v2/readiness
• Parameters: None
• Return Type: ReadinessResponse
• Throws/Returns Error: Network errors, HTTP errors, timeout errors
• Authentication: Should use the same authentication mechanism as other endpoints (likely API key header)
• Timeout: Should respect the client's configured timeout settings

Alternative Async Method (for languages supporting async/await)

readinessAsync() -> Promise<ReadinessResponse>

• Same behavior as readiness() but returns asynchronously

2. Existing Methods to Modify

No existing methods need modification. This is a purely additive change.

However, if the SDK has a generic health check or status checking interface/pattern, consider:

• If there's an existing liveness() method, ensure readiness() follows the same pattern
• If there's a health check interface or base class, ensure consistency in implementation

3. New Types/Models to Define

ReadinessResponse

ReadinessResponse {
  status: String  // The response body, expected to be "OK"
  httpStatus: Integer  // The HTTP status code, expected to be 200
}

Note: Depending on SDK design philosophy, this could be simplified:

• Simple approach: Return a boolean (true if ready, false or error otherwise)
• Detailed approach: Return the full response object as defined above
• Minimal approach: Return void/null and throw error on failure (caller only cares if it succeeds)

Recommendation: Follow the pattern established by the existing liveness() endpoint implementation in the SDK.

4. Tests to Write

Unit Tests

Test: Successful Readiness Check

• Mock HTTP client to return 200 status with "OK" body
• Call readiness()
• Assert response status is "OK" or true (depending on return type)
• Verify correct endpoint /v2/readiness was called
• Verify GET method was used

Test: Authentication Header Included

• Mock HTTP client
• Call readiness()
• Verify API key/authentication header was included in request
• Verify header format matches other endpoint calls

Test: Network Error Handling

• Mock HTTP client to throw network error
• Call readiness()
• Assert appropriate error is thrown or returned
• Verify error message is meaningful

Test: Non-200 Status Code

• Mock HTTP client to return 503 status
• Call readiness()
• Assert appropriate error is thrown or returned
• Verify status code is included in error information

Test: Timeout Handling

• Mock HTTP client to timeout
• Call readiness()
• Assert timeout error is thrown or returned

Test: Invalid Response Body

• Mock HTTP client to return 200 with unexpected body (e.g., empty, JSON, etc.)
• Call readiness()
• Assert method handles gracefully (either accepts it or handles error)

Integration Tests

Test: Live Readiness Check Against Test Server

• Configure SDK client with test server credentials
• Call readiness()
• Assert successful response
• Verify no errors thrown

Test: Readiness vs Liveness Consistency

• Call both readiness() and liveness() (if exists)
• Assert both follow same pattern
• Assert both succeed or handle errors similarly

5. Documentation to Update

API Reference Documentation

• Add new section for readiness() method
• Include:
  • Method signature
  • Purpose and use case explanation
  • Return type documentation
  • Possible errors/exceptions
  • Example code snippet showing basic usage
  • Comparison with liveness() if applicable

Example Entry:

### readiness()

Checks if the QStash service is ready to accept requests. This endpoint is commonly used 
in orchestration systems (like Kubernetes readiness probes) to determine when a service 
is ready to receive traffic.

**Returns**: ReadinessResponse indicating service readiness

**Throws**: 
- NetworkError: If unable to connect to QStash service
- TimeoutError: If request exceeds configured timeout
- AuthenticationError: If API credentials are invalid

**Example**:
[Language-specific example code]

README/Getting Started Guide

• If there's a health checking or monitoring section, add readiness check example
• If there's a "Common Patterns" section, consider adding readiness probe usage example

CHANGELOG

• Add entry under "Added" section:

  - New `readiness()` method to check QStash service readiness state
  - Complements existing liveness checks for orchestration systems
  

Migration Guide (if applicable)

• Not needed - this is a backward-compatible addition

6. Edge Cases and Considerations

Design Decisions for SDK Maintainers

Question 1: Should this be exposed at all?

• Readiness checks are typically infrastructure-level concerns
• Most application developers won't need this method
• Consider: Is the SDK targeting infrastructure/DevOps use cases?
• Recommendation: Include it for completeness, but don't prominently feature it in basic examples

Question 2: Return Type Philosophy

• Option A: Return boolean (simple, matches typical readiness probe usage)
• Option B: Return response object (consistent with other endpoints, more information)
• Option C: Return void, throw on error (simplest possible API)
• Recommendation: Match the pattern of existing liveness() method

Question 3: Separate Client vs Same Client

• Some SDKs separate health/admin endpoints from main API client
• Recommendation: If liveness() exists on main client, put readiness() there too

Error Handling Specifics

• Network unreachable: Should indicate service not ready
• 401/403 errors: Authentication issue (might still mean service is ready, auth is wrong)
• 404 error: Might indicate older server version without readiness endpoint
• 5xx errors: Service not ready
• Timeout: Service not ready or too slow

Retry Logic

• Readiness checks typically should NOT auto-retry
• Caller (like Kubernetes) will retry at their own interval
• Ensure SDK's global retry configuration doesn't apply to readiness endpoint

Caching

• Readiness state should NOT be cached
• Each call should make a fresh HTTP request
• Disable any response caching for this endpoint

---

This plan provides a complete, language-agnostic specification that SDK maintainers can implement in their respective languages (TypeScript, Python, Go, Rust, etc.) while maintaining consistency across all SDK clients.

---

This PR was generated by ardabot. Review the changes carefully before merging.
To request changes, leave review comments and ardabot will address them.
Original PR: https://github.com/upstash/qstash-server/pull/884