Plugin Configuration

/**
 * Install Auth plugin with configuration
 * @param block Configuration block for setting up authentication providers
 */
fun HttpClientConfig<*>.Auth(block: AuthConfig.() -> Unit)

/**
 * Core authentication plugin for Ktor client
 */
val Auth: ClientPlugin<AuthConfig>

import io.ktor.client.*
import io.ktor.client.plugins.auth.*

val client = HttpClient {
    Auth {
        // Add authentication providers here
    }
}

/**
 * Configuration used by Auth plugin
 */
class AuthConfig {
    /**
     * AuthProvider list to use
     */
    val providers: MutableList<AuthProvider>
    
    /**
     * Sets a custom function to control whether a response is unauthorized and should trigger a refresh / re-auth
     * By default checks against HTTP status 401
     * @param block Function that determines if a response should trigger re-authentication
     */
    fun reAuthorizeOnResponse(block: suspend (HttpResponse) -> Boolean)
}

Auth {
    // Configure custom unauthorized response detection
    reAuthorizeOnResponse { response ->
        response.status == HttpStatusCode.Unauthorized || 
        response.status == HttpStatusCode.Forbidden
    }
    
    // Add providers to the providers list
    basic { /* basic auth config */ }
    bearer { /* bearer auth config */ }
}

/**
 * Shows that request should skip auth and refresh token procedure
 */
val AuthCircuitBreaker: AttributeKey<Unit>

// Mark a request to skip authentication
val request = HttpRequestBuilder().apply {
    attributes.put(AuthCircuitBreaker, Unit)
}

/**
 * Get list of authentication providers from HTTP client
 */
val HttpClient.authProviders: List<AuthProvider>

/**
 * Get specific authentication provider by type from HTTP client
 * @return Provider instance or null if not found
 */
inline fun <reified T : AuthProvider> HttpClient.authProvider(): T?

import io.ktor.client.*
import io.ktor.client.plugins.auth.*
import io.ktor.client.plugins.auth.providers.*

// Get all providers
val allProviders = client.authProviders

// Get specific provider type
val basicProvider = client.authProvider<BasicAuthProvider>()
val bearerProvider = client.authProvider<BearerAuthProvider>()

// Clear tokens if needed
basicProvider?.clearToken()
bearerProvider?.clearToken()

/**
 * Base interface for authentication providers
 */
interface AuthProvider {
    /**
     * Determines whether credentials should be sent without waiting for HttpStatusCode.Unauthorized
     * @param request The HTTP request being processed
     * @return true if credentials should be sent proactively
     */
    fun sendWithoutRequest(request: HttpRequestBuilder): Boolean
    
    /**
     * Checks if the current provider is applicable to a request based on authentication header
     * @param auth Authentication header from WWW-Authenticate response
     * @return true if this provider can handle the authentication challenge
     */
    fun isApplicable(auth: HttpAuthHeader): Boolean
    
    /**
     * Adds authentication method headers and credentials to the request
     * @param request HTTP request builder to modify
     * @param authHeader Value of WWW-Authenticate header from failed response, if exists
     */
    suspend fun addRequestHeaders(request: HttpRequestBuilder, authHeader: HttpAuthHeader? = null)
    
    /**
     * Refreshes authentication token if required
     * @param response HTTP response that triggered token refresh
     * @return true if the token was successfully refreshed
     */
    suspend fun refreshToken(response: HttpResponse): Boolean
}