Basic Authentication

/**
 * Installs the client's BasicAuthProvider
 * @param block Configuration block for Basic authentication
 */
fun AuthConfig.basic(block: BasicAuthConfig.() -> Unit)

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

val client = HttpClient {
    Auth {
        basic {
            credentials {
                BasicAuthCredentials("username", "password")
            }
            realm = "MyRealm"
        }
    }
}

/**
 * Configuration for BasicAuthProvider
 */
class BasicAuthConfig {
    /**
     * Optional realm specification for the current provider
     */
    var realm: String?
    
    /**
     * Configures authentication credentials provider
     * @param block Suspend function that returns credentials or null
     */
    fun credentials(block: suspend () -> BasicAuthCredentials?)
    
    /**
     * Configures when to send credentials without waiting for HttpStatusCode.Unauthorized
     * @param block Function that determines based on request whether to send credentials proactively
     */
    fun sendWithoutRequest(block: (HttpRequestBuilder) -> Boolean)
}

basic {
    // Static credentials
    credentials {
        BasicAuthCredentials("user", "pass")
    }
    
    // Dynamic credentials
    credentials {
        val token = loadFromSecureStorage()
        if (token != null) BasicAuthCredentials(token.username, token.password)
        else null
    }
    
    // Send credentials proactively for specific paths
    sendWithoutRequest { request ->
        request.url.encodedPath.startsWith("/api/")
    }
    
    realm = "ProtectedArea"
}

/**
 * Contains credentials for BasicAuthProvider
 * @param username Username for authentication
 * @param password Password for authentication
 */
class BasicAuthCredentials(
    val username: String,
    val password: String
)

/**
 * Authentication provider for the Basic HTTP authentication scheme
 * The Basic authentication scheme can be used for logging in users
 */
class BasicAuthProvider(
    private val credentials: suspend () -> BasicAuthCredentials?,
    private val realm: String? = null,
    private val sendWithoutRequestCallback: (HttpRequestBuilder) -> Boolean = { false }
) : AuthProvider {
    
    // Note: clearToken() method is available but marked as @InternalAPI
    
    override fun sendWithoutRequest(request: HttpRequestBuilder): Boolean
    override fun isApplicable(auth: HttpAuthHeader): Boolean
    override suspend fun addRequestHeaders(request: HttpRequestBuilder, authHeader: HttpAuthHeader?)
    override suspend fun refreshToken(response: HttpResponse): Boolean
}

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

// Basic setup with static credentials
val client = HttpClient {
    Auth {
        basic {
            credentials {
                BasicAuthCredentials("alice", "password123")
            }
        }
    }
}

// Advanced setup with realm and conditional sending
val advancedClient = HttpClient {
    Auth {
        basic {
            credentials {
                // Load from secure storage or user input
                loadCredentialsFromStorage()
            }
            realm = "AdminArea"
            sendWithoutRequest { request ->
                // Only send for admin API paths
                request.url.encodedPath.startsWith("/admin/")
            }
        }
    }
}

// Note: clearToken() is available as internal API for clearing cached credentials