# Copyright (c) 2023 Yuki Kimoto
# MIT License

class Mojo::Headers {
  version_from Mojo;
  
  use Re;
  use StringList;
  use Hash;
  use Sort;
  use Regex;
  use StringBuffer;
  use Mojo::Cookie::Request;
  use Mojo::Cookie::Response;
  
  # Enumerations
  enum {
    MAX_LINE_SIZE_DEFAULT = 8192,
    MAX_LINES_DEFAULT = 100,
  }
  
  # Fields
  has headers_h : Hash;
  
  has max_line_size : wo int;
  
  method max_line_size : int () {
    
    if ($self->{max_line_size} < 0) {
      $self->{max_line_size} = &MAX_LINE_SIZE_DEFAULT;
    }
    
    return $self->{max_line_size};
  }
  
  has max_lines : wo int;
  
  method max_lines : int () {
    
    if ($self->{max_lines} < 0) {
      $self->{max_lines} = &MAX_LINES_DEFAULT;
    }
    
    return $self->{max_lines};
  }
  
  method max_lines_default : int () { return 100; }
  
  # Undocumented Fields
  has state : string;
  
  has limit : byte;
  
  has buffer : StringBuffer;
  
  has cache : List of string[];
  
  # Class Methods
  static method new : Mojo::Headers () {
    
    my $self = new Mojo::Headers;
    
    $self->{headers_h} = Hash->new;
    
    $self->{max_line_size} = -1;
    
    $self->{max_lines} = -1;
    
    $self->{buffer} = StringBuffer->new;
    
    return $self;
  }
  
  # Instance Methods
  method add : void ($name : string, $value : string) {
    
    unless ($name) {
      die "\$name must be defined.";
    }
    
    unless ($value) {
      die "\$value must be defined.";
    }
    
    if (Re->m($name, "[\x0d\x0a]")) {
      die "Invalid characters in the $name header.";
    }
    
    if (Re->m($value, "[\x0d\x0a]")) {
      die "Invalid characters in the value of the $name header.";
    }
    
    my $key = Fn->lc($name);
    
    my $new_value = (string)undef;
    if (my $cur_value = $self->{headers_h}->get_string($key)) {
      $new_value = "$cur_value, $value";
    }
    else {
      $new_value = $value;
    }
    
    $self->{headers_h}->set($key, $new_value);
  }
  
  method append : void ($name : string, $value : string) {
    
    $self->add($name, $value);
  }
  
  method clone : Mojo::Headers () {
    
    my $clone = Mojo::Headers->new;
    
    copy_fields $clone, $self, Mojo::Headers;
    
    for my $_ (@{$self->{headers_h}->keys}) {
      $clone->{headers_h}->set($_ => $self->{headers_h}->get_string($_));
    }
    
    $clone->{buffer} = $self->{buffer}->clone;
  }
  
  method dehop : void () {
    
    my $hop_by_hop = ["connection", "keep-alive", "proxy-authenticate", "proxy-authorization", "te trailer", "transfer-encoding upgrade"];
    
    for my $header (@$hop_by_hop) {
      $self->{headers_h}->delete($header);
    }
  }
  
  # TODO: Currently a header value is managed as a string if it has multiple values.
  # method every_header : string[] ($name : string) {}
  
  method from_hash : Mojo::Headers ($hash : Hash) {
    
    my $keys = $hash->keys;
    
    # Empty hash deletes all headers
    if (@$keys == 0) {
      $self->{headers_h} = Hash->new;
    }
    
    # Merge
    for my $header (@$keys) {
      my $value = $hash->get($header);
      
      my $values = (string[])undef;
      if (!$value) {
        $values = new string[0];
      }
      elsif ($value isa string[]) {
        $values = (string[])$value;
      }
      elsif ($value isa string) {
        $values = [(string)$value];
      }
      else {
        die "The type of the value \$value must be string, string[], or undef type.";
      }
      
      for my $value (@$values) {
        $self->add($header => $value);
      }
    }
  }
  
  method header : string ($name : string) {
    
    unless ($name) {
      die "\$name must be defined.";
    }
    
    my $headers = $self->{headers_h};
    
    my $key = Fn->lc($name);
    
    my $value = $self->{headers_h}->get_string($key);
    
    return $value;
  }
  
  method set_header : void ($name : string, $value : string) {
    
    $self->remove($name);
    
    $self->add($name, $value);
  }
  
  method is_finished : int () { return ($self->{state} // "") eq "finished"; }
  
  method is_limit_exceeded : int () { !!$self->{limit}; }
  
  method leftovers : string () {
    my $buffer = $self->{buffer};
    $self->{buffer} = undef;
    return $buffer->to_string;
  }
  
  # TODO
  # mthod links
  
  method names : string[] () {
    
    my $names = $self->{headers_h}->keys;
    
    Sort->sort_string_asc($names);
    
    return $names;
  }
  
  method parse : void ($chunk : string) {
    
    $self->{state} = "headers";
    $self->{buffer}->push($chunk);
    my $headers = $self->{cache} //= List->new(new string[][0]);
    my $buffer = $self->{buffer};
    my $size    = $self->max_line_size;
    my $lines   = $self->max_lines;
    
    # TODO: This is not needed. For SPVM or SPVM::Regex bug
    # $self->{state} = "finished"; removes $buffer if this line does not exists
    my $buffer_tmp = $buffer;
    
    my $offset = 0;
    while (1) {
      
      my $_ = Re->s($buffer, "^(.*?)\x0d?\x0a", "");
      
      unless ($_) {
        last;
      }
      
      my $line_buffer = StringBuffer->new($_->match->cap1);
      
      # TODO: This is not needed. For SPVM or SPVM::Regex bug
      # $self->{state} = "finished"; removes $line_buffer if this line does not exists
      my $line_buffer_tmp = $line_buffer;
      
      # Check line size limit
      if ($offset > $size || $headers->length >= $lines) {
        $self->{state} = "finished";
        $self->{limit} = 1;
        return;
      }
      
      # New header
      if (my $_ = Re->m($line_buffer, "^(\S[^:]*):\s*(.*)$")) {
        
        my $name = $_->cap1;
        my $value = $_->cap2;
        
        $headers->push([$name, $value]);
      }
      
      # Multi-line
      elsif ((my $_ = Re->s($line_buffer, "^\s+", "")) && $headers->length) {
        my $last_header = (string[])$headers->get($headers->length - 1);
        my $last_header_value = $last_header->[1];
        $last_header->[1] = $last_header_value . " " . $line_buffer->to_string;
      }
      
      # Empty line
      else {
        for (my $i = 0; $i < $headers->length; $i++) {
          
          my $items = (string[])$headers->get($i);
          
          my $name = (string)undef;
          for (my $item_index = 0; $item_index < @$items; $item_index++) {
            unless ($name) {
              $name = $items->[$item_index];
              next;
            }
            
            my $value = $items->[$item_index];
            
            $self->add($name, $value);
          }
        }
        
        $self->{state} = "finished";
        $self->{cache} = StringList->new;
        
        return;
      }
      
    }
   
    # Check line size limit
    if ($self->{buffer}->length > $size) {
      $self->{state} = "finished";
      $self->{limit} = 1;
    }
  }
  
  method to_string : string () {
    
    my $names = $self->names;
    
    my $buffer = StringBuffer->new;
    for my $name (@$names) {
      my $header_string = $self->header($name);
      if ($header_string) {
        $buffer->push("$name:");
        $buffer->push($header_string);
        $buffer->push("\r\n");
      }
    }
    
    my $string = $buffer->to_string;
    
    return $string;
  }
  
  method referer : string () { return $self->referrer; }
  
  method set_referer : void ($value : string) { $self->set_referrer($value); }
  
  method referrer : string () { return $self->header("Referer"); }
  
  method set_referrer : void ($value : string) { $self->set_header(Referer => $value); }
  
  method remove : void ($name : string) {
    
    unless ($name) {
      die "The name \$name must be defined";
    }
    
    my $key = Fn->lc($name);
    
    $self->{headers_h}->delete($key);
  }
  
  method to_hash : Hash () {
    
    my $hash = Hash->new;
    
    for my $name (@{$self->names}) {
      $hash->set($name => $self->header($name));
    }
    
    return $hash;
  }
  
  method accept : string () {

    my $value = $self->header("accept");

    return $value;
  }

  method set_accept : void ($value : string) {
    
    $self->set_header("accept" => $value);
  }

  method accept_charset : string () {

    my $value = $self->header("accept-charset");

    return $value;
  }

  method set_accept_charset : void ($value : string) {

    $self->set_header("accept-charset" => $value);
  }

  method accept_encoding : string () {

    my $value = $self->header("accept-encoding");

    return $value;
  }

  method set_accept_encoding : void ($value : string) {

    $self->set_header("accept-encoding" => $value);
  }

  method accept_language : string () {

    my $value = $self->header("accept-language");

    return $value;
  }

  method set_accept_language : void ($value : string) {

    $self->set_header("accept-language" => $value);
  }

  method accept_ranges : string () {

    my $value = $self->header("accept-ranges");

    return $value;
  }

  method set_accept_ranges : void ($value : string) {

    $self->set_header("accept-ranges" => $value);
  }

  method access_control_allow_origin : string () {

    my $value = $self->header("access-control-allow-origin");

    return $value;
  }

  method set_access_control_allow_origin : void ($value : string) {

    $self->set_header("access-control-allow-origin" => $value);
  }

  method allow : string () {

    my $value = $self->header("allow");

    return $value;
  }

  method set_allow : void ($value : string) {

    $self->set_header("allow" => $value);
  }

  method authorization : string () {

    my $value = $self->header("authorization");

    return $value;
  }

  method set_authorization : void ($value : string) {

    $self->set_header("authorization" => $value);
  }

  method cache_control : string () {

    my $value = $self->header("cache-control");

    return $value;
  }

  method set_cache_control : void ($value : string) {

    $self->set_header("cache-control" => $value);
  }

  method connection : string () {

    my $value = $self->header("connection");

    return $value;
  }

  method set_connection : void ($value : string) {

    $self->set_header("connection" => $value);
  }

  method content_disposition : string () {

    my $value = $self->header("content-disposition");

    return $value;
  }

  method set_content_disposition : void ($value : string) {

    $self->set_header("content-disposition" => $value);
  }

  method content_encoding : string () {

    my $value = $self->header("content-encoding");

    return $value;
  }

  method set_content_encoding : void ($value : string) {

    $self->set_header("content-encoding" => $value);
  }

  method content_language : string () {

    my $value = $self->header("content-language");

    return $value;
  }

  method set_content_language : void ($value : string) {

    $self->set_header("content-language" => $value);
  }

  method content_length : string () {

    my $value = $self->header("content-length");

    return $value;
  }

  method set_content_length : void ($value : string) {

    $self->set_header("content-length" => $value);
  }

  method content_location : string () {

    my $value = $self->header("content-location");

    return $value;
  }

  method set_content_location : void ($value : string) {

    $self->set_header("content-location" => $value);
  }

  method content_range : string () {

    my $value = $self->header("content-range");

    return $value;
  }

  method set_content_range : void ($value : string) {

    $self->set_header("content-range" => $value);
  }

  method content_security_policy : string () {

    my $value = $self->header("content-security-policy");

    return $value;
  }

  method set_content_security_policy : void ($value : string) {

    $self->set_header("content-security-policy" => $value);
  }

  method content_type : string () {

    my $value = $self->header("content-type");

    return $value;
  }

  method set_content_type : void ($value : string) {

    $self->set_header("content-type" => $value);
  }

  method cookie : string () {

    my $value = $self->header("cookie");

    return $value;
  }

  method set_cookie : void ($value : string) {

    $self->set_header("cookie" => $value);
  }

  method dnt : string () {

    my $value = $self->header("dnt");

    return $value;
  }

  method set_dnt : void ($value : string) {

    $self->set_header("dnt" => $value);
  }

  method date : string () {

    my $value = $self->header("date");

    return $value;
  }

  method set_date : void ($value : string) {

    $self->set_header("date" => $value);
  }

  method etag : string () {

    my $value = $self->header("etag");

    return $value;
  }

  method set_etag : void ($value : string) {

    $self->set_header("etag" => $value);
  }

  method expect : string () {

    my $value = $self->header("expect");

    return $value;
  }

  method set_expect : void ($value : string) {

    $self->set_header("expect" => $value);
  }

  method expires : string () {

    my $value = $self->header("expires");

    return $value;
  }

  method set_expires : void ($value : string) {

    $self->set_header("expires" => $value);
  }

  method host : string () {

    my $value = $self->header("host");

    return $value;
  }

  method set_host : void ($value : string) {

    $self->set_header("host" => $value);
  }

  method if_modified_since : string () {

    my $value = $self->header("if-modified-since");

    return $value;
  }

  method set_if_modified_since : void ($value : string) {

    $self->set_header("if-modified-since" => $value);
  }

  method if_none_match : string () {

    my $value = $self->header("if-none-match");

    return $value;
  }

  method set_if_none_match : void ($value : string) {

    $self->set_header("if-none-match" => $value);
  }

  method last_modified : string () {

    my $value = $self->header("last-modified");

    return $value;
  }

  method set_last_modified : void ($value : string) {

    $self->set_header("last-modified" => $value);
  }

  method link : string () {

    my $value = $self->header("link");

    return $value;
  }

  method set_link : void ($value : string) {

    $self->set_header("link" => $value);
  }

  method location : string () {

    my $value = $self->header("location");

    return $value;
  }

  method set_location : void ($value : string) {

    $self->set_header("location" => $value);
  }

  method origin : string () {

    my $value = $self->header("origin");

    return $value;
  }

  method set_origin : void ($value : string) {

    $self->set_header("origin" => $value);
  }

  method proxy_authenticate : string () {

    my $value = $self->header("proxy-authenticate");

    return $value;
  }

  method set_proxy_authenticate : void ($value : string) {

    $self->set_header("proxy-authenticate" => $value);
  }

  method proxy_authorization : string () {

    my $value = $self->header("proxy-authorization");

    return $value;
  }

  method set_proxy_authorization : void ($value : string) {

    $self->set_header("proxy-authorization" => $value);
  }

  method range : string () {

    my $value = $self->header("range");

    return $value;
  }

  method set_range : void ($value : string) {

    $self->set_header("range" => $value);
  }

  method sec_websocket_accept : string () {

    my $value = $self->header("sec-websocket-accept");

    return $value;
  }

  method set_sec_websocket_accept : void ($value : string) {

    $self->set_header("sec-websocket-accept" => $value);
  }

  method sec_websocket_extensions : string () {

    my $value = $self->header("sec-websocket-extensions");

    return $value;
  }

  method set_sec_websocket_extensions : void ($value : string) {

    $self->set_header("sec-websocket-extensions" => $value);
  }

  method sec_websocket_key : string () {

    my $value = $self->header("sec-websocket-key");

    return $value;
  }

  method set_sec_websocket_key : void ($value : string) {

    $self->set_header("sec-websocket-key" => $value);
  }

  method sec_websocket_protocol : string () {

    my $value = $self->header("sec-websocket-protocol");

    return $value;
  }

  method set_sec_websocket_protocol : void ($value : string) {

    $self->set_header("sec-websocket-protocol" => $value);
  }

  method sec_websocket_version : string () {

    my $value = $self->header("sec-websocket-version");

    return $value;
  }

  method set_sec_websocket_version : void ($value : string) {

    $self->set_header("sec-websocket-version" => $value);
  }

  method server : string () {

    my $value = $self->header("server");

    return $value;
  }

  method set_server : void ($value : string) {

    $self->set_header("server" => $value);
  }

  method server_timing : string () {

    my $value = $self->header("server-timing");

    return $value;
  }

  method set_server_timing : void ($value : string) {

    $self->set_header("server-timing" => $value);
  }

  method get_set_cookie : string () {

    my $value = $self->header("set-cookie");

    return $value;
  }

  method set_set_cookie : void ($value : string) {

    $self->set_header("set-cookie" => $value);
  }

  method status : string () {

    my $value = $self->header("status");

    return $value;
  }

  method set_status : void ($value : string) {

    $self->set_header("status" => $value);
  }

  method strict_transport_security : string () {

    my $value = $self->header("strict-transport-security");

    return $value;
  }

  method set_strict_transport_security : void ($value : string) {

    $self->set_header("strict-transport-security" => $value);
  }

  method te : string () {

    my $value = $self->header("te");

    return $value;
  }

  method set_te : void ($value : string) {

    $self->set_header("te" => $value);
  }

  method trailer : string () {

    my $value = $self->header("trailer");

    return $value;
  }

  method set_trailer : void ($value : string) {

    $self->set_header("trailer" => $value);
  }

  method transfer_encoding : string () {

    my $value = $self->header("transfer-encoding");

    return $value;
  }

  method set_transfer_encoding : void ($value : string) {

    $self->set_header("transfer-encoding" => $value);
  }

  method upgrade : string () {

    my $value = $self->header("upgrade");

    return $value;
  }

  method set_upgrade : void ($value : string) {

    $self->set_header("upgrade" => $value);
  }

  method user_agent : string () {

    my $value = $self->header("user-agent");

    return $value;
  }

  method set_user_agent : void ($value : string) {

    $self->set_header("user-agent" => $value);
  }

  method vary : string () {

    my $value = $self->header("vary");

    return $value;
  }

  method set_vary : void ($value : string) {

    $self->set_header("vary" => $value);
  }

  method www_authenticate : string () {

    my $value = $self->header("www-authenticate");

    return $value;
  }

  method set_www_authenticate : void ($value : string) {

    $self->set_header("www-authenticate" => $value);
  }
  
}

__END__

TODO

package Mojo::Headers;
use Mojo::Base -base;

use Carp       qw(croak);
use Mojo::Util qw(header_params monkey_patch);

has max_line_size => sub { $ENV{MOJO_MAX_LINE_SIZE} || 8192 };
has max_lines     => sub { $ENV{MOJO_MAX_LINES}     || 100 };

# Common headers
my %NAMES = map { lc() => $_ } (
  qw(Accept Accept-Charset Accept-Encoding Accept-Language Accept-Ranges Access-Control-Allow-Origin Allow),
  qw(Authorization Cache-Control Connection Content-Disposition Content-Encoding Content-Language Content-Length),
  qw(Content-Location Content-Range Content-Security-Policy Content-Type Cookie DNT Date ETag Expect Expires Host),
  qw(If-Modified-Since If-None-Match Last-Modified Link Location Origin Proxy-Authenticate Proxy-Authorization),
  qw(Range Sec-WebSocket-Accept Sec-WebSocket-Extensions Sec-WebSocket-Key Sec-WebSocket-Protocol),
  qw(Sec-WebSocket-Version Server Server-Timing Set-Cookie Status Strict-Transport-Security TE Trailer),
  qw(Transfer-Encoding Upgrade User-Agent Vary WWW-Authenticate)
);
for my $header (keys %NAMES) {
  my $name = $header;
  $name =~ y/-/_/;
  monkey_patch __PACKAGE__, $name, sub {
    my $self = shift;
    $self->{headers}{$header} = [@_] and return $self if @_;
    return undef unless my $headers = $self->{headers}{$header};
    return join ', ', @$headers;
  };
}

# Hop-by-hop headers
my @HOP_BY_HOP
  = map {lc} qw(Connection Keep-Alive Proxy-Authenticate Proxy-Authorization TE Trailer Transfer-Encoding Upgrade);

sub add {
  my ($self, $name) = (shift, shift);

  tr/\x0d\x0a// and croak "Invalid characters in $name header" for @_;

  # Make sure we have a normal case entry for name
  my $key = lc $name;
  $self->{names}{$key} //= $name unless $NAMES{$key};
  push @{$self->{headers}{$key}}, @_;

  return $self;
}

sub append {
  my ($self, $name, $value) = @_;
  my $old = $self->header($name);
  return $self->header($name => defined $old ? "$old, $value" : $value);
}

sub clone {
  my $self = shift;

  my $clone = $self->new;
  %{$clone->{names}} = %{$self->{names} // {}};
  @{$clone->{headers}{$_}} = @{$self->{headers}{$_}} for keys %{$self->{headers}};

  return $clone;
}

sub dehop {
  my $self = shift;
  delete @{$self->{headers}}{@HOP_BY_HOP};
  return $self;
}

sub every_header { shift->{headers}{lc shift} // [] }

sub from_hash {
  my ($self, $hash) = @_;

  # Empty hash deletes all headers
  delete $self->{headers} if keys %{$hash} == 0;

  # Merge
  for my $header (keys %$hash) {
    my $value = $hash->{$header};
    $self->add($header => ref $value eq 'ARRAY' ? @$value : $value);
  }

  return $self;
}

sub header {
  my ($self, $name) = (shift, shift);

  # Replace
  return $self->remove($name)->add($name, @_) if @_;

  return undef unless my $headers = $self->{headers}{lc $name};
  return join ', ', @$headers;
}

sub is_finished { (shift->{state} // '') eq 'finished' }

sub is_limit_exceeded { !!shift->{limit} }

sub leftovers { delete shift->{buffer} }

sub links {
  my ($self, $links) = @_;

  return $self->link(join(', ', map {qq{<$links->{$_}>; rel="$_"}} sort keys %$links)) if $links;

  my $header = $self->link // '';
  my $data   = {};
  while ($header =~ s/^[,\s]*<(.+?)>//) {
    my $target = $1;
    (my $params, $header) = header_params $header;
    $data->{$params->{rel}} //= {%$params, link => $target} if defined $params->{rel};
  }

  return $data;
}

sub names {
  my $self = shift;
  return [map { $NAMES{$_} || $self->{names}{$_} } sort keys %{$self->{headers}}];
}

sub parse {
  my ($self, $chunk) = @_;

  $self->{state} = 'headers';
  $self->{buffer} .= $chunk;
  my $headers = $self->{cache} //= [];
  my $size    = $self->max_line_size;
  my $lines   = $self->max_lines;
  while ($self->{buffer} =~ s/^(.*?)\x0d?\x0a//) {
    my $line = $1;

    # Check line size limit
    if ($+[0] > $size || @$headers >= $lines) {
      @$self{qw(state limit)} = ('finished', 1);
      return $self;
    }

    # New header
    if ($line =~ /^(\S[^:]*):\s*(.*)$/) { push @$headers, [$1, $2] }

    # Multi-line
    elsif ($line =~ s/^\s+// && @$headers) { $headers->[-1][1] .= " $line" }

    # Empty line
    else {
      $self->add(@$_) for @$headers;
      @$self{qw(state cache)} = ('finished', []);
      return $self;
    }
  }

  # Check line size limit
  @$self{qw(state limit)} = ('finished', 1) if length $self->{buffer} > $size;

  return $self;
}

sub referer  { shift->referrer(@_) }
sub referrer { shift->header(Referer => @_) }

sub remove {
  my ($self, $name) = @_;
  delete $self->{headers}{lc $name};
  return $self;
}

sub to_hash {
  my ($self, $multi) = @_;
  return {map { $_ => $self->{headers}{lc $_} } @{$self->names}} if $multi;
  return {map { $_ => $self->header($_) } @{$self->names}};
}

sub to_string {
  my $self = shift;

  # Make sure multi-line values are formatted correctly
  my @headers;
  for my $name (@{$self->names}) { push @headers, "$name: $_" for @{$self->{headers}{lc $name}} }

  return join "\x0d\x0a", @headers;
}

1;

=encoding utf8

=head1 NAME

Mojo::Headers - HTTP headers

=head1 SYNOPSIS

  use Mojo::Headers;

  # Parse
  my $headers = Mojo::Headers->new;
  $headers->parse("Content-Length: 42\x0d\x0a");
  $headers->parse("Content-Type: text/html\x0d\x0a\x0d\x0a");
  say $headers->content_length;
  say $headers->content_type;

  # Build
  my $headers = Mojo::Headers->new;
  $headers->content_length(42);
  $headers->content_type('text/plain');
  say $headers->to_string;

=head1 DESCRIPTION

L<Mojo::Headers> is a container for HTTP headers, based on L<RFC 7230|https://tools.ietf.org/html/rfc7230> and L<RFC
7231|https://tools.ietf.org/html/rfc7231>.

=head1 ATTRIBUTES

L<Mojo::Headers> implements the following attributes.

=head2 max_line_size

  my $size = $headers->max_line_size;
  $headers = $headers->max_line_size(1024);

Maximum header line size in bytes, defaults to the value of the C<MOJO_MAX_LINE_SIZE> environment variable or C<8192>
(8KiB).

=head2 max_lines

  my $num  = $headers->max_lines;
  $headers = $headers->max_lines(200);

Maximum number of header lines, defaults to the value of the C<MOJO_MAX_LINES> environment variable or C<100>.

=head1 METHODS

L<Mojo::Headers> inherits all methods from L<Mojo::Base> and implements the following new ones.

=head2 add

  $headers = $headers->add(Foo => 'one value');
  $headers = $headers->add(Foo => 'first value', 'second value');

Add header with one or more lines.

  # "Vary: Accept
  #  Vary: Accept-Encoding"
  $headers->add(Vary => 'Accept')->add(Vary => 'Accept-Encoding')->to_string;

=head2 append

  $headers = $headers->append(Vary => 'Accept-Encoding');

Append value to header and flatten it if necessary.

  # "Vary: Accept"
  $headers->append(Vary => 'Accept')->to_string;

  # "Vary: Accept, Accept-Encoding"
  $headers->vary('Accept')->append(Vary => 'Accept-Encoding')->to_string;

=head2 clone

  my $clone = $headers->clone;

Return a new L<Mojo::Headers> object cloned from these headers.

=head2 dehop

  $headers = $headers->dehop;

Remove hop-by-hop headers that should not be retransmitted.

=head2 every_header

  my $all = $headers->every_header('Location');

Similar to L</"header">, but returns all headers sharing the same name as an array reference.

  # Get first header value
  say $headers->every_header('Location')->[0];

=head2 from_hash

  $headers = $headers->from_hash({'Cookie' => 'a=b'});
  $headers = $headers->from_hash({'Cookie' => ['a=b', 'c=d']});
  $headers = $headers->from_hash({});

Parse headers from a hash reference, an empty hash removes all headers.

=head2 header

  my $value = $headers->header('Foo');
  $headers  = $headers->header(Foo => 'one value');
  $headers  = $headers->header(Foo => 'first value', 'second value');

Get or replace the current header values.

=head2 is_finished

  my $bool = $headers->is_finished;

Check if header parser is finished.

=head2 is_limit_exceeded

  my $bool = $headers->is_limit_exceeded;

Check if headers have exceeded L</"max_line_size"> or L</"max_lines">.

=head2 leftovers

  my $bytes = $headers->leftovers;

Get and remove leftover data from header parser.

=head2 names

  my $names = $headers->names;

Return an array reference with all currently defined headers.

  # Names of all headers
  say for @{$headers->names};

=head2 parse

  $headers = $headers->parse("Content-Type: text/plain\x0d\x0a\x0d\x0a");

Parse formatted headers.

=head2 remove

  $headers = $headers->remove('Foo');

Remove a header.

=head2 to_hash

  my $single = $headers->to_hash;
  my $multi  = $headers->to_hash(1);

Turn headers into hash reference, array references to represent multiple headers with the same name are disabled by
default.

  say $headers->to_hash->{DNT};

=head2 to_string

  my $str = $headers->to_string;

Turn headers into a string, suitable for HTTP messages.


=head1 ADDITIONAL METHODS

Additionally, the following shortcuts are available, for accessing and manipulating commonly-used headers:

=head2 accept

  my $accept = $headers->accept;
  $headers   = $headers->accept('application/json');

Get or replace current header value, shortcut for the C<Accept> header.

=head2 accept_charset

  my $charset = $headers->accept_charset;
  $headers    = $headers->accept_charset('UTF-8');

Get or replace current header value, shortcut for the C<Accept-Charset> header.

=head2 accept_encoding

  my $encoding = $headers->accept_encoding;
  $headers     = $headers->accept_encoding('gzip');

Get or replace current header value, shortcut for the C<Accept-Encoding> header.

=head2 accept_language

  my $language = $headers->accept_language;
  $headers     = $headers->accept_language('de, en');

Get or replace current header value, shortcut for the C<Accept-Language> header.

=head2 accept_ranges

  my $ranges = $headers->accept_ranges;
  $headers   = $headers->accept_ranges('bytes');

Get or replace current header value, shortcut for the C<Accept-Ranges> header.

=head2 access_control_allow_origin

  my $origin = $headers->access_control_allow_origin;
  $headers   = $headers->access_control_allow_origin('*');

Get or replace current header value, shortcut for the C<Access-Control-Allow-Origin> header from L<Cross-Origin
Resource Sharing|https://www.w3.org/TR/cors/>.

=head2 allow

  my $allow = $headers->allow;
  $headers  = $headers->allow('GET, POST');

Get or replace current header value, shortcut for the C<Allow> header.

=head2 authorization

  my $authorization = $headers->authorization;
  $headers          = $headers->authorization('Basic Zm9vOmJhcg==');

Get or replace current header value, shortcut for the C<Authorization> header.

=head2 cache_control

  my $cache_control = $headers->cache_control;
  $headers          = $headers->cache_control('max-age=1, no-cache');

Get or replace current header value, shortcut for the C<Cache-Control> header.

=head2 connection

  my $connection = $headers->connection;
  $headers       = $headers->connection('close');

Get or replace current header value, shortcut for the C<Connection> header.

=head2 content_disposition

  my $disposition = $headers->content_disposition;
  $headers        = $headers->content_disposition('foo');

Get or replace current header value, shortcut for the C<Content-Disposition> header.

=head2 content_encoding

  my $encoding = $headers->content_encoding;
  $headers     = $headers->content_encoding('gzip');

Get or replace current header value, shortcut for the C<Content-Encoding> header.

=head2 content_language

  my $language = $headers->content_language;
  $headers     = $headers->content_language('en');

Get or replace current header value, shortcut for the C<Content-Language> header.

=head2 content_length

  my $len  = $headers->content_length;
  $headers = $headers->content_length(4000);

Get or replace current header value, shortcut for the C<Content-Length> header.

=head2 content_location

  my $location = $headers->content_location;
  $headers     = $headers->content_location('http://127.0.0.1/foo');

Get or replace current header value, shortcut for the C<Content-Location> header.

=head2 content_range

  my $range = $headers->content_range;
  $headers  = $headers->content_range('bytes 2-8/100');

Get or replace current header value, shortcut for the C<Content-Range> header.

=head2 content_security_policy

  my $policy = $headers->content_security_policy;
  $headers   = $headers->content_security_policy('default-src https:');

Get or replace current header value, shortcut for the C<Content-Security-Policy> header from L<Content Security Policy
1.0|https://www.w3.org/TR/CSP/>.

=head2 content_type

  my $type = $headers->content_type;
  $headers = $headers->content_type('text/plain');

Get or replace current header value, shortcut for the C<Content-Type> header.

=head2 cookie

  my $cookie = $headers->cookie;
  $headers   = $headers->cookie('f=b');

Get or replace current header value, shortcut for the C<Cookie> header from L<RFC
6265|https://tools.ietf.org/html/rfc6265>.

=head2 date

  my $date = $headers->date;
  $headers = $headers->date('Sun, 17 Aug 2008 16:27:35 GMT');

Get or replace current header value, shortcut for the C<Date> header.

=head2 dnt

  my $dnt  = $headers->dnt;
  $headers = $headers->dnt(1);

Get or replace current header value, shortcut for the C<DNT> (Do Not Track) header, which has no specification yet, but
is very commonly used.

=head2 etag

  my $etag = $headers->etag;
  $headers = $headers->etag('"abc321"');

Get or replace current header value, shortcut for the C<ETag> header.

=head2 expect

  my $expect = $headers->expect;
  $headers   = $headers->expect('100-continue');

Get or replace current header value, shortcut for the C<Expect> header.

=head2 expires

  my $expires = $headers->expires;
  $headers    = $headers->expires('Thu, 01 Dec 1994 16:00:00 GMT');

Get or replace current header value, shortcut for the C<Expires> header.

=head2 host

  my $host = $headers->host;
  $headers = $headers->host('127.0.0.1');

Get or replace current header value, shortcut for the C<Host> header.

=head2 if_modified_since

  my $date = $headers->if_modified_since;
  $headers = $headers->if_modified_since('Sun, 17 Aug 2008 16:27:35 GMT');

Get or replace current header value, shortcut for the C<If-Modified-Since> header.

=head2 if_none_match

  my $etag = $headers->if_none_match;
  $headers = $headers->if_none_match('"abc321"');

Get or replace current header value, shortcut for the C<If-None-Match> header.

=head2 last_modified

  my $date = $headers->last_modified;
  $headers = $headers->last_modified('Sun, 17 Aug 2008 16:27:35 GMT');

Get or replace current header value, shortcut for the C<Last-Modified> header.

=head2 link

  my $link = $headers->link;
  $headers = $headers->link('<http://127.0.0.1/foo/3>; rel="next"');

Get or replace current header value, shortcut for the C<Link> header from L<RFC
5988|https://tools.ietf.org/html/rfc5988>.

=head2 links

  my $links = $headers->links;
  $headers  = $headers->links({next => 'http://example.com/foo', prev => 'http://example.com/bar'});

Get or set web links from or to C<Link> header according to L<RFC 5988|http://tools.ietf.org/html/rfc5988>.

  # Extract information about next page
  say $headers->links->{next}{link};
  say $headers->links->{next}{title};

=head2 location

  my $location = $headers->location;
  $headers     = $headers->location('http://127.0.0.1/foo');

Get or replace current header value, shortcut for the C<Location> header.

=head2 origin

  my $origin = $headers->origin;
  $headers   = $headers->origin('http://example.com');

Get or replace current header value, shortcut for the C<Origin> header from L<RFC
6454|https://tools.ietf.org/html/rfc6454>.

=head2 proxy_authenticate

  my $authenticate = $headers->proxy_authenticate;
  $headers         = $headers->proxy_authenticate('Basic "realm"');

Get or replace current header value, shortcut for the C<Proxy-Authenticate> header.

=head2 proxy_authorization

  my $authorization = $headers->proxy_authorization;
  $headers          = $headers->proxy_authorization('Basic Zm9vOmJhcg==');

Get or replace current header value, shortcut for the C<Proxy-Authorization> header.

=head2 range

  my $range = $headers->range;
  $headers  = $headers->range('bytes=2-8');

Get or replace current header value, shortcut for the C<Range> header.

=head2 referer

  my $referrer = $headers->referer;
  $headers     = $headers->referer('http://example.com');

Alias for L</"referrer">.

=head2 referrer

  my $referrer = $headers->referrer;
  $headers     = $headers->referrer('http://example.com');

Get or replace current header value, shortcut for the C<Referer> header, there was a typo in L<RFC
2068|https://tools.ietf.org/html/rfc2068> which resulted in C<Referer> becoming an official header.

=head2 sec_websocket_accept

  my $accept = $headers->sec_websocket_accept;
  $headers   = $headers->sec_websocket_accept('s3pPLMBiTxaQ9kYGzzhZRbK+xOo=');

Get or replace current header value, shortcut for the C<Sec-WebSocket-Accept> header from L<RFC
6455|https://tools.ietf.org/html/rfc6455>.

=head2 sec_websocket_extensions

  my $extensions = $headers->sec_websocket_extensions;
  $headers       = $headers->sec_websocket_extensions('foo');

Get or replace current header value, shortcut for the C<Sec-WebSocket-Extensions> header from L<RFC
6455|https://tools.ietf.org/html/rfc6455>.

=head2 sec_websocket_key

  my $key  = $headers->sec_websocket_key;
  $headers = $headers->sec_websocket_key('dGhlIHNhbXBsZSBub25jZQ==');

Get or replace current header value, shortcut for the C<Sec-WebSocket-Key> header from L<RFC
6455|https://tools.ietf.org/html/rfc6455>.

=head2 sec_websocket_protocol

  my $proto = $headers->sec_websocket_protocol;
  $headers  = $headers->sec_websocket_protocol('sample');

Get or replace current header value, shortcut for the C<Sec-WebSocket-Protocol> header from L<RFC
6455|https://tools.ietf.org/html/rfc6455>.

=head2 sec_websocket_version

  my $version = $headers->sec_websocket_version;
  $headers    = $headers->sec_websocket_version(13);

Get or replace current header value, shortcut for the C<Sec-WebSocket-Version> header from L<RFC
6455|https://tools.ietf.org/html/rfc6455>.

=head2 server

  my $server = $headers->server;
  $headers   = $headers->server('Mojo');

Get or replace current header value, shortcut for the C<Server> header.

=head2 server_timing

  my $timing = $headers->server_timing;
  $headers   = $headers->server_timing('app;desc=Mojolicious;dur=0.0001');

Get or replace current header value, shortcut for the C<Server-Timing> header from L<Server
Timing|https://www.w3.org/TR/server-timing/>.

=head2 set_cookie

  my $cookie = $headers->set_cookie;
  $headers   = $headers->set_cookie('f=b; path=/');

Get or replace current header value, shortcut for the C<Set-Cookie> header from L<RFC
6265|https://tools.ietf.org/html/rfc6265>.

=head2 status

  my $status = $headers->status;
  $headers   = $headers->status('200 OK');

Get or replace current header value, shortcut for the C<Status> header from L<RFC
3875|https://tools.ietf.org/html/rfc3875>.

=head2 strict_transport_security

  my $policy = $headers->strict_transport_security;
  $headers   = $headers->strict_transport_security('max-age=31536000');

Get or replace current header value, shortcut for the C<Strict-Transport-Security> header from L<RFC
6797|https://tools.ietf.org/html/rfc6797>.

=head2 te

  my $te   = $headers->te;
  $headers = $headers->te('chunked');

Get or replace current header value, shortcut for the C<TE> header.

=head2 trailer

  my $trailer = $headers->trailer;
  $headers    = $headers->trailer('X-Foo');

Get or replace current header value, shortcut for the C<Trailer> header.

=head2 transfer_encoding

  my $encoding = $headers->transfer_encoding;
  $headers     = $headers->transfer_encoding('chunked');

Get or replace current header value, shortcut for the C<Transfer-Encoding> header.

=head2 upgrade

  my $upgrade = $headers->upgrade;
  $headers    = $headers->upgrade('websocket');

Get or replace current header value, shortcut for the C<Upgrade> header.

=head2 user_agent

  my $agent = $headers->user_agent;
  $headers  = $headers->user_agent('Mojo/1.0');

Get or replace current header value, shortcut for the C<User-Agent> header.

=head2 vary

  my $vary = $headers->vary;
  $headers = $headers->vary('*');

Get or replace current header value, shortcut for the C<Vary> header.

=head2 www_authenticate

  my $authenticate = $headers->www_authenticate;
  $headers         = $headers->www_authenticate('Basic realm="realm"');

Get or replace current header value, shortcut for the C<WWW-Authenticate> header.

=head1 SEE ALSO

L<Mojolicious>, L<Mojolicious::Guides>, L<https://mojolicious.org>.

=cut
