Context Keys

DeepIntShield uses Go’s context.Context to pass configuration and metadata through the request lifecycle. Context keys allow you to customize request behavior, pass request-specific settings, and read metadata set by DeepIntShield.

Request Configuration Keys

These keys can be set before making a request to customize behavior.

Extra Headers

Pass custom headers with individual requests. Headers are automatically propagated to the provider.

ctx := context.Background()

extraHeaders := map[string][]string{
    "user-id":    {"user-123"},
    "session-id": {"session-abc"},
}
ctx = context.WithValue(ctx, schemas.DeepIntShieldContextKeyExtraHeaders, extraHeaders)

response, err := client.ChatCompletionRequest(schemas.NewDeepIntShieldContext(ctx, schemas.NoDeadline), &schemas.DeepIntShieldChatRequest{
    Provider: schemas.OpenAI,
    Model:    "gpt-4o-mini",
    Input:    messages,
})

Note

See Custom Headers Per Request for detailed information on header handling and security restrictions.

API Key Selection

DeepIntShield supports selecting a specific key by ID or name. When both are present, ID takes priority.

By ID

Explicitly select a key by its unique ID.

ctx := context.WithValue(ctx, schemas.DeepIntShieldContextKeyAPIKeyID, "key-uuid-1234")

By Name

Explicitly select a named API key from your configured keys.

ctx := context.WithValue(ctx, schemas.DeepIntShieldContextKeyAPIKeyName, "premium-key")

Direct Key

Bypass key selection and provide credentials directly. Useful for dynamic key scenarios.

directKey := schemas.Key{
    Value:  "sk-direct-api-key",
    Models: []string{"gpt-4o"},
    Weight: 1.0,
}
ctx := context.WithValue(ctx, schemas.DeepIntShieldContextKeyDirectKey, directKey)

Skip Key Selection

Skip the key selection process entirely and pass an empty key to the provider. Useful for providers that don’t require authentication or when using ambient credentials.

ctx := context.WithValue(ctx, schemas.DeepIntShieldContextKeySkipKeySelection, true)

Session Stickiness (Session ID)

Bind a session to a specific API key so that requests with the same session ID consistently use the same key. Useful for predictable rate-limit buckets, cost attribution per user, and consistent model routing per session.

On the first request for a session ID, DeepIntShield selects a key (via weighted random) and caches the binding in the KV store. Subsequent requests with the same session ID reuse the cached key as long as it remains valid. If the cached key is no longer in the supported set (disabled, removed, or model support changed), DeepIntShield re-selects and overwrites the cache.

ctx := context.WithValue(ctx, schemas.DeepIntShieldContextKeySessionID, "user-123-session-abc")

Session TTL

Optional. Controls how long the session-to-key binding is cached. If not set, DeepIntShield uses DefaultSessionStickyTTL (1 hour). The TTL is refreshed on each request so active sessions do not expire.

ctx := context.WithValue(ctx, schemas.DeepIntShieldContextKeySessionTTL, 30*time.Minute)

Request ID

Set a custom request ID for tracking and correlation.

ctx := context.WithValue(ctx, schemas.DeepIntShieldContextKeyRequestID, "req-12345-abc")

Custom URL Path

Append a custom path to the provider’s base URL. Useful for accessing provider-specific endpoints.

ctx := context.WithValue(ctx, schemas.DeepIntShieldContextKeyURLPath, "/custom/endpoint")

Raw Request Body

Send a raw request body instead of DeepIntShield’s standardized format. The provider receives your payload as-is. You must both enable the context key AND set the RawRequestBody field on your request.

// Prepare your raw JSON payload
rawPayload := []byte(`{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}],
    "custom_field": "provider-specific-value"
}`)

// Enable raw request body mode
ctx := context.WithValue(ctx, schemas.DeepIntShieldContextKeyUseRawRequestBody, true)

// Set the raw body on the request
response, err := client.ChatCompletionRequest(schemas.NewDeepIntShieldContext(ctx, schemas.NoDeadline), &schemas.DeepIntShieldChatRequest{
    Provider:       schemas.OpenAI,
    Model:          "gpt-4o",
    RawRequestBody: rawPayload,  // This will be sent directly to the provider
})

Note

When using raw request body, DeepIntShield bypasses its request conversion and sends your payload directly to the provider. You’re responsible for ensuring the payload matches the provider’s expected format.

Send Back Raw Request/Response

Include the original request or response in the ExtraFields for debugging.

// Include raw request in response
ctx := context.WithValue(ctx, schemas.DeepIntShieldContextKeySendBackRawRequest, true)

// Include raw provider response
ctx := context.WithValue(ctx, schemas.DeepIntShieldContextKeySendBackRawResponse, true)

Access in response:

response, _ := client.ChatCompletionRequest(schemas.NewDeepIntShieldContext(ctx, schemas.NoDeadline), request)
if response.ChatResponse != nil {
    rawReq := response.ChatResponse.ExtraFields.RawRequest
    rawResp := response.ChatResponse.ExtraFields.RawResponse
}

Passthrough Extra Parameters

Enable passthrough mode for extra parameters. When enabled, any parameters in ExtraParams will be merged directly into the request sent to the provider, bypassing DeepIntShield’s parameter filtering.

ctx := context.WithValue(ctx, schemas.DeepIntShieldContextKeyPassthroughExtraParams, true)

response, err := client.ChatCompletionRequest(schemas.NewDeepIntShieldContext(ctx, schemas.NoDeadline), &schemas.DeepIntShieldChatRequest{
    Provider: schemas.OpenAI,
    Model:    "gpt-4o-mini",
    Input:    messages,
    Params: &schemas.ChatParameters{
        ExtraParams: map[string]interface{}{
            "custom_param": "value",
            "another_param": 123,
            "nested_param": map[string]interface{}{
                "nested_key": "nested_value",
            },
        },
    },
})

When enabled, the extra parameters are merged into the JSON request body sent to the provider. This allows you to pass provider-specific parameters that DeepIntShield doesn’t natively support.

Note

• This feature only works for JSON requests, not multipart/form-data requests
• Parameters already handled by DeepIntShield (like addWatermark, enhancePrompt) are not duplicated - they appear in their proper location
• Nested parameters (e.g., parameters.custom_field) are merged recursively with existing nested structures

Response Metadata Keys

These keys are set by DeepIntShield and can be read from the context after a request completes. They’re particularly useful in plugins and hooks.

Selected Key Information

After DeepIntShield selects an API key, it stores the selection details in the context.

// Get the selected key's ID
keyID := ctx.Value(schemas.DeepIntShieldContextKeySelectedKeyID).(string)

// Get the selected key's name
keyName := ctx.Value(schemas.DeepIntShieldContextKeySelectedKeyName).(string)

Retry and Fallback Information

Track retry attempts and fallback progression.

// Number of retries attempted (0 = first attempt)
retries := ctx.Value(schemas.DeepIntShieldContextKeyNumberOfRetries).(int)

// Fallback index (0 = primary, 1 = first fallback, etc.)
fallbackIdx := ctx.Value(schemas.DeepIntShieldContextKeyFallbackIndex).(int)

// Fallback request ID (set when using a fallback provider)
fallbackReqID := ctx.Value(schemas.DeepIntShieldContextKeyFallbackRequestID).(string)

Stream End Indicator

For streaming responses, indicates when the stream has completed.

isStreamEnd := ctx.Value(schemas.DeepIntShieldContextKeyStreamEndIndicator).(bool)

Note

Plugin developers: When implementing custom streaming in PreLLMHook or PostLLMHook, make sure to mark DeepIntShieldContextKeyStreamEndIndicator as true at the end of the stream for proper cleanup.

Integration Type

Identifies which integration format is being used (useful in gateway scenarios).

integrationType := ctx.Value(schemas.DeepIntShieldContextKeyIntegrationType).(string)
// e.g., "openai", "anthropic", "bedrock"

Complete Example

Here’s a comprehensive example showing multiple context keys in use:

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/maximhq/deepintshield"
    "github.com/maximhq/deepintshield/core/schemas"
)

func makeRequest(client *deepintshield.DeepIntShield) {
    // Start with background context
    ctx := context.Background()

    // Add request tracking
    ctx = context.WithValue(ctx, schemas.DeepIntShieldContextKeyRequestID, "req-001")

    // Add custom headers for the provider
    extraHeaders := map[string][]string{
        "x-correlation-id": {"corr-12345"},
        "x-tenant-id":      {"tenant-abc"},
    }
    ctx = context.WithValue(ctx, schemas.DeepIntShieldContextKeyExtraHeaders, extraHeaders)

    // Request raw response for debugging
    ctx = context.WithValue(ctx, schemas.DeepIntShieldContextKeySendBackRawResponse, true)

    // Make the request
    messages := []schemas.DeepIntShieldMessage{
        {Role: "user", Content: &schemas.DeepIntShieldMessageContent{Text: deepintshield.Ptr("Hello!")}},
    }

    response, err := client.ChatCompletionRequest(schemas.NewDeepIntShieldContext(ctx, schemas.NoDeadline), &schemas.DeepIntShieldChatRequest{
        Provider: schemas.OpenAI,
        Model:    "gpt-4o-mini",
        Input:    messages,
    })

    if err != nil {
        log.Printf("Request failed: %v", err)
        return
    }

    // Access response metadata
    if response.ChatResponse != nil {
        extra := response.ChatResponse.ExtraFields
        fmt.Printf("Provider: %s\n", extra.Provider)
        fmt.Printf("Latency: %dms\n", extra.Latency)

        if extra.RawResponse != nil {
            fmt.Printf("Raw response available for debugging\n")
        }
    }
}

Context Keys Reference

Key	Type	Direction	Description
DeepIntShieldContextKeyVirtualKey	string	Set	Virtual key identifier
DeepIntShieldContextKeyAPIKeyName	string	Set	Explicit API key name selection
DeepIntShieldContextKeyAPIKeyID	string	Set	Explicit API key ID selection (priority over name)
DeepIntShieldContextKeyRequestID	string	Set	Custom request ID for tracking
DeepIntShieldContextKeyFallbackRequestID	string	Read	Request ID when using fallback
DeepIntShieldContextKeyDirectKey	schemas.Key	Set	Direct key credentials
DeepIntShieldContextKeySelectedKeyID	string	Read	Selected key’s ID
DeepIntShieldContextKeySelectedKeyName	string	Read	Selected key’s name
DeepIntShieldContextKeyNumberOfRetries	int	Read	Number of retry attempts
DeepIntShieldContextKeyFallbackIndex	int	Read	Current fallback index
DeepIntShieldContextKeyStreamEndIndicator	bool	Read	Stream completion flag
DeepIntShieldContextKeySkipKeySelection	bool	Set	Skip key selection
DeepIntShieldContextKeySessionID	string	Set	Session ID for key stickiness (requires KV store)
DeepIntShieldContextKeySessionTTL	time.Duration	Set	TTL for session-to-key cache (default: 1 hour)
DeepIntShieldContextKeyExtraHeaders	map[string][]string	Set	Custom request headers
DeepIntShieldContextKeyURLPath	string	Set	Custom URL path suffix
DeepIntShieldContextKeyUseRawRequestBody	bool	Set	Use raw request body
DeepIntShieldContextKeySendBackRawRequest	bool	Set	Include raw request in response
DeepIntShieldContextKeySendBackRawResponse	bool	Set	Include raw response
DeepIntShieldContextKeyPassthroughExtraParams	bool	Set	Enable passthrough for extra parameters
DeepIntShieldContextKeyIntegrationType	string	Read	Integration format type
DeepIntShieldContextKeyUserAgent	string	Read	Request user agent

Next Steps

• Provider Configuration - Configure providers and keys
• Streaming Responses - Real-time response handling
• Tool Calling - Enable AI function calling
• Core Features - Advanced DeepIntShield capabilities