// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
 
using YamlDotNet.Serialization;
 
namespace Aspire.Hosting.Kubernetes.Resources;
 
/// <summary>
/// Defines the specification for a Kubernetes Service resource.
/// </summary>
/// <remarks>
/// This class represents various attributes that define the behavior and configuration
/// of a Kubernetes Service, such as type, IP addresses, load balancer settings, traffic
/// policies, selectors, ports, and session affinity options.
/// </remarks>
[YamlSerializable]
public sealed class ServiceSpecV1
{
    /// <summary>
    /// Specifies the IP address assigned to the Kubernetes Service within the cluster.
    /// </summary>
    /// <remarks>
    /// The ClusterIP is used internally within the Kubernetes cluster to allow services
    /// to communicate with each other. If set to "None", the service will not be assigned
    /// a ClusterIP and will act as a headless service, suitable for direct pod communication.
    /// This property may be null when the cluster IP is not explicitly specified.
    /// </remarks>
    [YamlMember(Alias = "clusterIP")]
    public string? ClusterIp { get; set; }
 
    /// <summary>
    /// Gets or sets the IP address to assign to the external LoadBalancer of the Service.
    /// </summary>
    /// <remarks>
    /// If specified, this explicitly sets the LoadBalancer's IP address. This property is used when deploying
    /// a Service with type set to "LoadBalancer" in Kubernetes. The actual usage of this field depends on the
    /// cloud provider or environment where the Kubernetes cluster is hosted. If not set, the IP address will
    /// be dynamically assigned by the environment.
    /// </remarks>
    [YamlMember(Alias = "loadBalancerIP")]
    public string? LoadBalancerIp { get; set; }
 
    /// <summary>
    /// Specifies the external DNS name for the Kubernetes Service associated with a ServiceSpecV1.
    /// </summary>
    /// <remarks>
    /// This property is used with the "ExternalName" service type in Kubernetes to map a service
    /// to an external DNS name rather than an IP or other resources within the cluster.
    /// </remarks>
    [YamlMember(Alias = "externalName")]
    public string? ExternalName { get; set; }
 
    /// <summary>
    /// Gets or sets the type of the Kubernetes Service.
    /// </summary>
    /// <remarks>
    /// Specifies the type of Service to be created. Common types include:
    /// "ClusterIP", "NodePort", "LoadBalancer", and "ExternalName".
    /// Defaults to "ClusterIP" if not specified.
    /// </remarks>
    [YamlMember(Alias = "type")]
    public string Type { get; set; } = "ClusterIP";
 
    /// <summary>
    /// Represents the session affinity configuration for a Kubernetes Service.
    /// </summary>
    /// <remarks>
    /// This property specifies the configuration details of session affinity, which ensures that requests
    /// from a client are directed to the same backend pod. This is typically used for stateful applications
    /// requiring client-based stickiness.
    /// </remarks>
    [YamlMember(Alias = "sessionAffinityConfig")]
    public SessionAffinityConfigV1? SessionAffinityConfig { get; set; }
 
    /// <summary>
    /// Specifies the traffic distribution policy for the Kubernetes Service.
    /// </summary>
    /// <remarks>
    /// This property defines how network traffic is distributed across the service's associated pods or endpoints.
    /// It determines the mechanism or strategy used for traffic routing, which could include methods such as load-balancing or specific traffic shaping configurations.
    /// </remarks>
    [YamlMember(Alias = "trafficDistribution")]
    public string? TrafficDistribution { get; set; }
 
    /// <summary>
    /// Represents the selector field in the Kubernetes Service specification.
    /// </summary>
    /// <remarks>
    /// The selector is a key-value pair dictionary used to identify a set of pods
    /// that the Service targets. The Service routes traffic to these pods based on the selector definition.
    /// </remarks>
    [YamlMember(Alias = "selector")]
    public Dictionary<string, string> Selector { get; set; } = [];
 
    /// <summary>
    /// Indicates whether node ports should be automatically allocated for a service of type LoadBalancer.
    /// </summary>
    /// <remarks>
    /// When set to true, this property ensures that node ports are allocated for the load balancer service,
    /// enabling external access through specific ports. This setting is optional and can be used based
    /// on service configuration requirements.
    /// </remarks>
    [YamlMember(Alias = "allocateLoadBalancerNodePorts")]
    public bool? AllocateLoadBalancerNodePorts { get; set; }
 
    /// <summary>
    /// Represents a list of cluster IP addresses assigned to the Kubernetes Service.
    /// </summary>
    /// <remarks>
    /// The property is used to define multiple IP addresses for the Service, enabling support for more than one IP family.
    /// Commonly used in dual-stack networking configurations where both IPv4 and IPv6 IP addresses are specified.
    /// The property is immutable after creation and is managed by the Kubernetes system.
    /// </remarks>
    [YamlMember(Alias = "clusterIPs")]
    public List<string> ClusterIPs { get; } = [];
 
    /// <summary>
    /// Represents a list of external IP addresses associated with the service.
    /// </summary>
    /// <remarks>
    /// ExternalIPs specifies additional IP addresses for the service that are externally visible.
    /// These IP addresses are usually outside the cluster and can be used to route traffic to the service.
    /// </remarks>
    [YamlMember(Alias = "externalIPs")]
    public List<string> ExternalIPs { get; } = [];
 
    /// <summary>
    /// A list of IP families (e.g., IPv4, IPv6) used by the Kubernetes Service.
    /// </summary>
    /// <remarks>
    /// Specifies the IP address families the Service supports or is associated with.
    /// The order of families in the list can influence the assignment of IP addresses
    /// when the Service is created or updated. This is relevant when defining dual-stack services
    /// or specific network configurations requiring certain IP families.
    /// </remarks>
    [YamlMember(Alias = "ipFamilies")]
    public List<string> IpFamilies { get; } = [];
 
    /// <summary>
    /// Specifies the class of the load balancer to be used for the service.
    /// </summary>
    /// <remarks>
    /// This property allows the user to define a specific load balancer implementation
    /// or configuration class for the service. It is especially useful in environments
    /// where multiple load balancer options are available, enabling customization based
    /// on requirements or provider specifications.
    /// When set, this value is used to select the corresponding load balancer class during service creation.
    /// </remarks>
    [YamlMember(Alias = "loadBalancerClass")]
    public string? LoadBalancerClass { get; set; }
 
    /// <summary>
    /// Specifies a list of IP address ranges that are allowed to access
    /// the Kubernetes Service when the Service type is "LoadBalancer".
    /// </summary>
    /// <remarks>
    /// The LoadBalancerSourceRanges property defines a list of CIDR (Classless Inter-Domain Routing)
    /// ranges that restrict access to the Service's load balancer. If not set, access is not restricted
    /// based on IP ranges and is determined by the cloud provider or default behavior.
    /// </remarks>
    [YamlMember(Alias = "loadBalancerSourceRanges")]
    public List<string> LoadBalancerSourceRanges { get; } = [];
 
    /// <summary>
    /// Represents the collection of port configurations for a Kubernetes Service.
    /// </summary>
    /// <remarks>
    /// This property defines the list of ports through which the service can be accessed.
    /// Each port is configured using the <see cref="ServicePortV1"/> class, specifying details such as the port number, protocol, target port, and node port.
    /// It is key in exposing and routing traffic to the appropriate underlying workloads.
    /// </remarks>
    [YamlMember(Alias = "ports")]
    public List<ServicePortV1> Ports { get; } = [];
 
    /// <summary>
    /// Gets or sets a value indicating whether to publish the addresses of not-ready pods for a Kubernetes Service.
    /// </summary>
    /// <remarks>
    /// When set to true, the Service will publish the IP addresses of pods even if the pods are not ready.
    /// This can be useful when a Service needs to route traffic to pods during their initialization phase
    /// or when readiness probes are not strictly necessary.
    /// </remarks>
    [YamlMember(Alias = "publishNotReadyAddresses")]
    public bool? PublishNotReadyAddresses { get; set; }
 
    /// <summary>
    /// Gets or sets the health check node port for the Kubernetes Service.
    /// </summary>
    /// <remarks>
    /// This property specifies the port number that is used for health checks when the external traffic policy is set to "Local".
    /// If not specified, the system will automatically allocate a node port.
    /// </remarks>
    [YamlMember(Alias = "healthCheckNodePort")]
    public int? HealthCheckNodePort { get; set; }
 
    /// <summary>
    /// Specifies how external traffic is routed to the Service's underlying network endpoints.
    /// </summary>
    /// <remarks>
    /// The property is used to define whether external traffic routed to the Service should preserve
    /// the client source IP address or be routed directly. Acceptable values include:
    /// - "Cluster": Traffic is routed via the cluster network and source IP addresses are not preserved.
    /// - "Local": Traffic is routed directly to the Service endpoints and source IP addresses are preserved.
    /// This setting is particularly useful for load balancing scenarios and for complying with
    /// specific application requirements where source IP preservation is a priority.
    /// </remarks>
    [YamlMember(Alias = "externalTrafficPolicy")]
    public string? ExternalTrafficPolicy { get; set; }
 
    /// <summary>
    /// Gets or sets the internal traffic policy for the Kubernetes Service.
    /// </summary>
    /// <remarks>
    /// This property defines the policy dictating how traffic is routed internally
    /// within the cluster. It can be used to configure traffic routing behavior
    /// for services with internal communication within the cluster.
    /// </remarks>
    [YamlMember(Alias = "internalTrafficPolicy")]
    public string? InternalTrafficPolicy { get; set; }
 
    /// <summary>
    /// Defines the IP family policy for a Kubernetes Service in API version V1.
    /// </summary>
    /// <remarks>
    /// This property determines the policy under which IP families (IPv4, IPv6) are assigned to the Service.
    /// It can control whether the Service prefers or requires a specific IP family or supports both.
    /// </remarks>
    [YamlMember(Alias = "ipFamilyPolicy")]
    public string? IpFamilyPolicy { get; set; }
 
    /// <summary>
    /// Defines the session affinity setting for a Kubernetes Service in API version V1.
    /// </summary>
    /// <remarks>
    /// Session affinity determines how traffic is routed to a service. It helps in maintaining
    /// connections from the same client to the same pod, enabling stateful communication
    /// and enhancing user experience for applications requiring persistent sessions.
    /// </remarks>
    [YamlMember(Alias = "sessionAffinity")]
    public string? SessionAffinity { get; set; }
}