How DS2API Handles Request Abortion and Uniform Error Contracts

DS2API implements deterministic request abortion through a lease-based lifecycle mechanism and enforces a consistent four-field JSON schema for all error responses across OpenAI and Gemini compatible endpoints.

The DS2API open-source proxy (CJackHwang/ds2api) manages long-running streaming connections to AI providers while ensuring predictable error handling. Understanding how DS2API handles request abortion and error contracts is essential for building reliable client integrations that can gracefully terminate streams and parse error responses using a single, provider-agnostic schema.

Lease-Based Request Abortion Architecture

DS2API's streaming endpoints implement a deterministic, race-free abort contract using short-lived leases that tie authentication objects to unique identifiers. This architecture prevents resource leaks when clients terminate connections prematurely.

Creating Stream Leases

When a client initiates a streamed request to the OpenAI-compatible /v1/chat/completions endpoint on Vercel, the system creates a lease that binds the request's authentication state to a temporary identifier. In internal/httpapi/openai/chat/vercel_stream.go, the handleVercelStreamPrepare function calls holdStreamLease to generate this binding:

leaseID := h.holdStreamLease(a)

The holdStreamLease method stores the lease in h.streamLeases alongside an expiration timestamp. This lease reserves the auth.RequestAuth object, ensuring that per-account resources like tokens and rate-limit counters remain allocated for the duration of the stream.

Explicit Client Abort via Release Endpoint

Clients terminate streams intentionally by calling the release endpoint with the query parameter __stream_release=1. The request body must include the previously issued lease_id. The handleVercelStreamRelease handler in vercel_stream.go validates the secret, parses the lease_id, and invokes releaseStreamLease:

h.releaseStreamLease(leaseID)

This function removes the lease from the active map and calls h.Auth.Release(lease.Auth), returning the authentication resources to the available pool. The server responds with a JSON confirmation: {"success":true}.

Automatic Cleanup of Expired Leases

To prevent resource leaks from abandoned connections, DS2API implements proactive garbage collection. The sweepExpiredStreamLeases function runs before every prepare and release operation, invoking popExpiredLeasesLocked to identify timed-out entries and releaseExpiredAuths to free their associated authentication objects. This background sweep guarantees that crashed clients or network failures never permanently exhaust account quotas.

Testing the Abort Flow

The test suite validates the abortion contract through simulated client termination. In internal/testsuite/edge_cases_abort.go, the test reads only the first 512-byte chunk of a response, closes the connection body, and records the truncated response as "aborted_after_first_chunk". This verifies that the server correctly handles premature termination without entering an error state.

Uniform Error Contract Implementation

Regardless of upstream provider, all DS2API HTTP endpoints return structured JSON error objects containing four standardized fields: code, message, status, and param. This consistency eliminates the need for provider-specific error parsing logic on the client side.

OpenAI-Compatible Error Responses

In internal/httpapi/openai/shared/handler_errors.go, the WriteOpenAIError function generates standardized error payloads for OpenAI-compatible endpoints:

func WriteOpenAIError(w http.ResponseWriter, status int, message string) {
    WriteOpenAIErrorWithCode(w, status, message, "")
}

The underlying WriteOpenAIErrorWithCode function populates the JSON response using helper functions OpenAIErrorType (mapping HTTP status to strings like "invalid_request_error") and OpenAIErrorCode (mapping status to machine-readable codes). The final payload follows this structure:

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable description",
    "status": "INVALID_ARGUMENT",
    "param": null
  }
}

Gemini Error Response Mapping

The Gemini implementation in internal/httpapi/gemini/handler_errors.go mirrors this contract through the writeGeminiError function. It maps HTTP status codes to Google-style status strings such as "UNAUTHENTICATED" for 401 errors:

func writeGeminiError(w http.ResponseWriter, status int, message string) {
    errorStatus := "INVALID_ARGUMENT"
    switch status {
    case http.StatusUnauthorized:
        errorStatus = "UNAUTHENTICATED"
    // … additional mappings …
    }
    writeJSON(w, status, map[string]any{
        "error": map[string]any{
            "code":    status,
            "message": message,
            "status":  errorStatus,
        },
    })
}

Both implementations reserve the param field as null for future field-level error hints while maintaining identical top-level schemas.

Practical Implementation Examples

The following patterns demonstrate how to interact with DS2API's abortion mechanism and error handling in production code.

Starting a Streamed Request

To initiate a lease-protected stream, POST to the completion endpoint with the __stream_prepare=1 query flag:

// POST /v1/chat/completions?__stream_prepare=1
payload := map[string]any{
    "model": "gpt-4o-mini",
    "messages": []any{{"role": "user", "content": "Hello"}},
    "stream": true,
}
resp, _ := http.Post(streamPrepareURL, "application/json", json.NewEncoder(payload))

var init struct {
    LeaseID string `json:"lease_id"`
}
json.NewDecoder(resp.Body).Decode(&init)
// init.LeaseID now contains the lease identifier

Aborting the Stream

When terminating a stream early, send the lease ID to the release endpoint:

abortPayload := map[string]any{
    "lease_id": init.LeaseID,
}
req, _ := http.NewRequest(http.MethodPost,
    streamReleaseURL+"?__stream_release=1",
    json.NewEncoder(abortPayload))
req.Header.Set("Content-Type", "application/json")
client.Do(req)
// Server responds with: {"success":true}

Consuming Uniform Error Responses

Client applications can parse error responses from any DS2API endpoint using a single struct definition:

resp, err := client.Do(req)
if err != nil { /* handle network error */ }
if resp.StatusCode >= 400 {
    var e struct {
        Error struct {
            Code    string `json:"code"`
            Message string `json:"message"`
            Status  string `json:"status"`
            Param   any    `json:"param"`
        } `json:"error"`
    }
    json.NewDecoder(resp.Body).Decode(&e)
    fmt.Printf("API error: %s (%s) – %s\n",
        e.Error.Code, e.Error.Status, e.Error.Message)
}

This structure works identically for both OpenAI-compatible and Gemini endpoints due to the shared schema implementation.

Key Source Files

The request abortion and error handling implementations span several critical files in the CJackHwang/ds2api repository:

• internal/httpapi/openai/chat/vercel_stream.go: Contains holdStreamLease, releaseStreamLease, sweepExpiredStreamLeases, and the __stream_prepare/__stream_release handlers.
• internal/httpapi/openai/shared/handler_errors.go: Implements WriteOpenAIError, OpenAIErrorType, and OpenAIErrorCode for standardized error generation.
• internal/httpapi/gemini/handler_errors.go: Provides writeGeminiError to maintain contract parity with OpenAI endpoints.
• internal/testsuite/edge_cases_abort.go: Validates the abort flow through simulated client terminations.
• internal/auth/request.go: Supplies the Auth.Release method called during lease cleanup.

Summary

DS2API implements a deterministic approach to streaming request management and error standardization:

• Lease-based abortion prevents resource leaks through explicit lease_id tracking and automatic expiration sweeping in vercel_stream.go.
• Explicit release endpoint (__stream_release=1) allows clients to immediately free authentication resources when terminating streams.
• Uniform JSON error contract across OpenAI and Gemini endpoints uses four consistent fields: code, message, status, and param.
• Centralized error writers in handler_errors.go ensure provider-agnostic error handling for client applications.

Frequently Asked Questions

How does DS2API prevent resource leaks when a client disconnects unexpectedly?

DS2API prevents resource leaks through a combination of explicit lease tracking and automatic cleanup. The sweepExpiredStreamLeases function runs before every stream operation to remove timed-out leases and release their associated auth.RequestAuth objects via Auth.Release. This guarantees that abandoned streams eventually free their reserved quota regardless of client behavior.

What is the structure of error responses in DS2API?

All error responses follow a uniform JSON structure containing four fields: code (machine-readable identifier), message (human-readable description), status (Google-style canonical status string like "INVALID_ARGUMENT"), and param (reserved as null for future field-level hints). This schema applies identically to both OpenAI-compatible and Gemini endpoints.

How do I properly abort a streaming request in DS2API?

To abort a stream, first obtain the lease_id from the initial __stream_prepare=1 response. Then send a POST request to the release endpoint with __stream_release=1 query parameter and the lease ID in the request body. The server will call releaseStreamLease to immediately free the authentication resources and return {"success":true}.

Where are the error handling utilities implemented in the source code?

OpenAI-compatible error utilities reside in internal/httpapi/openai/shared/handler_errors.go, including WriteOpenAIError and status mapping functions. Gemini error handling is implemented in internal/httpapi/gemini/handler_errors.go via the writeGeminiError function. Both files ensure the four-field error contract is maintained across all API endpoints.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}