package com.flightticket.service;

import com.flightticket.dto.ratelimit.ApiUsageStats;
import com.flightticket.dto.ratelimit.RateLimitConfigRequest;
import com.flightticket.dto.ratelimit.RateLimitConfigResponse;

import java.util.List;
import java.util.UUID;

/**
 * Service interface for rate limiting functionality
 * Requirements: 14.1, 14.2, 14.3, 14.4, 14.5
 */
public interface RateLimitingService {
    
    /**
     * Check if a request is allowed based on rate limits
     * Requirements: 14.1, 14.2
     * 
     * @param agencyId The agency making the request
     * @param endpoint The endpoint being accessed
     * @return true if request is allowed, false otherwise
     */
    boolean isRequestAllowed(UUID agencyId, String endpoint);
    
    /**
     * Record a request for rate limiting purposes
     * Requirements: 14.3
     * 
     * @param agencyId The agency making the request
     * @param endpoint The endpoint being accessed
     */
    void recordRequest(UUID agencyId, String endpoint);
    
    /**
     * Get API usage statistics for an agency and endpoint
     * Requirements: 14.3
     * 
     * @param agencyId The agency ID
     * @param endpoint The endpoint
     * @return Usage statistics
     */
    ApiUsageStats getUsageStats(UUID agencyId, String endpoint);
    
    /**
     * Get all API usage statistics for an agency
     * Requirements: 14.3
     * 
     * @param agencyId The agency ID
     * @return List of usage statistics
     */
    List<ApiUsageStats> getAllUsageStats(UUID agencyId);
    
    /**
     * Create or update rate limit configuration
     * Requirements: 14.1, 14.5
     * 
     * @param request The rate limit configuration request
     * @param updatedBy The user making the change
     * @return The created/updated configuration
     */
    RateLimitConfigResponse configureRateLimit(RateLimitConfigRequest request, UUID updatedBy);
    
    /**
     * Get rate limit configuration for an agency and endpoint
     * Requirements: 14.1
     * 
     * @param agencyId The agency ID
     * @param endpointPattern The endpoint pattern
     * @return The rate limit configuration
     */
    RateLimitConfigResponse getRateLimitConfig(UUID agencyId, String endpointPattern);
    
    /**
     * Get all rate limit configurations for an agency
     * Requirements: 14.1
     * 
     * @param agencyId The agency ID
     * @return List of rate limit configurations
     */
    List<RateLimitConfigResponse> getAllRateLimitConfigs(UUID agencyId);
    
    /**
     * Delete rate limit configuration
     * Requirements: 14.5
     * 
     * @param configId The configuration ID
     */
    void deleteRateLimitConfig(UUID configId);
    
    /**
     * Check for rate limit violations and send alerts
     * Requirements: 14.4
     */
    void checkAndAlertViolations();
    
    /**
     * Get the time to wait before retrying (in seconds)
     * Requirements: 14.2
     * 
     * @param agencyId The agency ID
     * @param endpoint The endpoint
     * @return Seconds to wait before retry
     */
    int getRetryAfterSeconds(UUID agencyId, String endpoint);
}