File Coverage

lib/HTTP/Promise/Headers/CacheControl.pm
Criterion Covered Total %
statement 45 58 77.5
branch 7 10 70.0
condition 2 3 66.6
subroutine 16 29 55.1
pod 21 21 100.0
total 91 121 75.2


line stmt bran cond sub pod time code
1             ##----------------------------------------------------------------------------
2             ## Asynchronous HTTP Request and Promise - ~/lib/HTTP/Promise/Headers/CacheControl.pm
3             ## Version v0.1.0
4             ## Copyright(c) 2022 DEGUEST Pte. Ltd.
5             ## Author: Jacques Deguest <jack@deguest.jp>
6             ## Created 2022/05/06
7             ## Modified 2022/05/06
8             ## All rights reserved.
9             ##
10             ##
11             ## This program is free software; you can redistribute it and/or modify it
12             ## under the same terms as Perl itself.
13             ##----------------------------------------------------------------------------
14             package HTTP::Promise::Headers::CacheControl;
15             BEGIN
16             {
17 3     3   3420 use strict;
  3         7  
  3         96  
18 3     3   15 use warnings;
  3         7  
  3         87  
19 3     3   18 use warnings::register;
  3         8  
  3         352  
20 3     3   19 use parent qw( HTTP::Promise::Headers::Generic );
  3         11  
  3         15  
21 3     3   269 our $VERSION = 'v0.1.0';
22             };
23              
24 3     3   20 use strict;
  3         8  
  3         79  
25 3     3   17 use warnings;
  3         9  
  3         2234  
26              
27             sub init
28             {
29 3     3 1 383123 my $self = shift( @_ );
30 3         227 $self->{properties} = {};
31 3         24 $self->{params} = [];
32 3         16 $self->{_needs_quotes} = {};
33 3 50 66     54 @_ = () if( @_ == 1 && $self->_is_a( $_[0] => 'Module::Generic::Null' ) );
34 3 100       94 if( @_ )
35             {
36 2         12 my $this = shift( @_ );
37 2 50       17 my $ref = $self->new_array( $self->_is_array( $this ) ? $this : [split( /[[:blank:]\h]*(?<!\\)\,[[:blank:]\h]*/, "$this" )] );
38 2         135 my $params = $self->params;
39 2         1742 my $props = $self->properties;
40 2         2658 foreach my $pair ( @$ref )
41             {
42 4         36 my( $prop, $val ) = split( /=/, $pair, 2 );
43 4         21 $props->{ $prop } = $val;
44 4         100 $params->push( $prop );
45             }
46             }
47 3         63 $self->{_init_strict_use_sub} = 1;
48 3 50       49 $self->SUPER::init( @_ ) || return( $self->pass_error );
49 3         31 $self->_field_name( 'Cache-Control' );
50 3         2418 return( $self );
51             }
52              
53 7     7 1 1299 sub as_string { return( shift->_set_get_properties_as_string ); }
54              
55 2     2 1 440 sub immutable { return( shift->_set_get_property_boolean( 'immutable', @_ ) ); }
56              
57 4     4 1 65 sub max_age { return( shift->_set_get_property_number( 'max-age', @_ ) ); }
58              
59 0     0 1 0 sub max_stale { return( shift->_set_get_property_number( 'max-stale', @_ ) ); }
60              
61 0     0 1 0 sub min_fresh { return( shift->_set_get_property_number( 'min-fresh', @_ ) ); }
62              
63 0     0 1 0 sub must_revalidate { return( shift->_set_get_property_boolean( 'must-revalidate', @_ ) ); }
64              
65 0     0 1 0 sub must_understand { return( shift->_set_get_property_boolean( 'must-understand', @_ ) ); }
66              
67 0     0 1 0 sub no_cache { return( shift->_set_get_property_boolean( 'no-cache', @_ ) ); }
68              
69 0     0 1 0 sub no_store { return( shift->_set_get_property_boolean( 'no-store', @_ ) ); }
70              
71 0     0 1 0 sub no_transform { return( shift->_set_get_property_boolean( 'no-transform', @_ ) ); }
72              
73 0     0 1 0 sub only_if_cached { return( shift->_set_get_property_boolean( 'only-if-cached', @_ ) ); }
74              
75 21     21 1 71 sub params { return( shift->_set_get_array_as_object( 'params', @_ ) ); }
76              
77 3 100   3 1 459 sub property { return( shift->_set_get_property_value( @_, ( @_ > 1 ? { needs_quotes => 1 } : () ) ) ); }
78              
79 21     21 1 80 sub properties { return( shift->_set_get_hash_as_mix_object( 'properties', @_ ) ); }
80              
81 0     0 1 0 sub private { return( shift->_set_get_property_boolean( 'private', @_ ) ); }
82              
83 0     0 1 0 sub proxy_revalidate { return( shift->_set_get_property_boolean( 'proxy-revalidate', @_ ) ); }
84              
85 1     1 1 20 sub public { return( shift->_set_get_property_boolean( 'public', @_ ) ); }
86              
87 0     0 1 0 sub s_maxage { return( shift->_set_get_property_number( 's-maxage', @_ ) ); }
88              
89 0     0 1 0 sub stale_if_error { return( shift->_set_get_property_number( 'stale-if-error', @_ ) ); }
90              
91 0     0 1 0 sub stale_while_revalidate { return( shift->_set_get_property_number( 'stale-while-revalidate', @_ ) ); }
92              
93 8     8   28 sub _needs_quotes { return( shift->_set_get_hash_as_mix_object( '_needs_quotes', @_ ) ); }
94              
95             1;
96             # NOTE: POD
97             __END__
98              
99             =encoding utf-8
100              
101             =head1 NAME
102              
103             HTTP::Promise::Headers::CacheControl - Cache-Control Header Field
104              
105             =head1 SYNOPSIS
106              
107             use HTTP::Promise::Headers::CacheControl;
108             my $cc = HTTP::Promise::Headers::CacheControl->new ||
109             die( HTTP::Promise::Headers::CacheControl->error, "\n" );
110              
111             =head1 VERSION
112              
113             v0.1.0
114              
115             =head1 DESCRIPTION
116              
117             The following is an extract from Mozilla documentation.
118              
119             The C<Cache-Control> HTTP header field holds directives (instructions) — in both requests and responses — that control caching in browsers and shared caches (e.g. Proxies, CDNs).
120              
121             =head1 METHODS
122              
123             The following known properties can be set with those methods. If you want to remove a property, simply set a value of C<undef>.
124              
125             When you set a new property, it will be added at the end.
126              
127             If you want to set or get non-standard property, use the L</property> method
128              
129             This class keeps track of the order of the properties set to ensure repeatability and predictability.
130              
131             =head2 as_string
132              
133             Returns a string representation of the C<Cache-Control> object.
134              
135             =head2 immutable
136              
137             This takes a boolean value. When the value is true, this property is set if it does not already exist, and if false, it is removed.
138              
139             If no value is provided, it returns true if the property is already set and false if it is not.
140              
141             The C<immutable> response directive indicates that the response will not be updated while it's fresh.
142              
143             Cache-Control: public, max-age=604800, immutable
144              
145             =head2 max_age
146              
147             If a value is provided, this takes an integer, and set the property to that value. If it exists already, it simply change the property value, otherwise it adds it at the end.
148              
149             When no value is provided, this returns the numeric value of that property if it exists, or an empty string otherwise.
150              
151             The max-age=N response directive indicates that the response remains fresh until N seconds after the response is generated.
152              
153             Cache-Control: max-age=604800
154              
155             This is used in request and in response.
156              
157             =head2 max_stale
158              
159             If a value is provided, this takes an integer, and set the property to that value. If it exists already, it simply change the property value, otherwise it adds it at the end.
160              
161             When no value is provided, this returns the numeric value of that property if it exists, or an empty string otherwise.
162              
163             The C<max-stale=N> request directive indicates that the client allows a stored response that is stale within N seconds.
164              
165             Cache-Control: max-stale=3600
166              
167             =head2 min_fresh
168              
169             The C<min-fresh=N> request directive indicates that the client allows a stored response that is fresh for at least N seconds.
170              
171             Cache-Control: min-fresh=600
172              
173             =head2 must_revalidate
174              
175             If a value is provided, this takes an integer, and set the property to that value. If it exists already, it simply change the property value, otherwise it adds it at the end.
176              
177             When no value is provided, this returns the numeric value of that property if it exists, or an empty string otherwise.
178              
179             This takes a boolean value. When the value is true, this property is set if it does not already exist, and if false, it is removed.
180              
181             If no value is provided, it returns true if the property is already set and false if it is not.
182              
183             The C<must-revalidate> response directive indicates that the response can be stored in caches and can be reused while fresh. If the response becomes stale, it must be validated with the origin server before reuse.
184              
185             Typically, C<must-revalidate> is used with max-age.
186              
187             Cache-Control: max-age=604800, must-revalidate
188              
189             =head2 must_understand
190              
191             This takes a boolean value. When the value is true, this property is set if it does not already exist, and if false, it is removed.
192              
193             If no value is provided, it returns true if the property is already set and false if it is not.
194              
195             The must-understand response directive indicates that a cache should store the response only if it understands the requirements for caching based on status code.
196              
197             must-understand should be coupled with no-store for fallback behavior.
198              
199             Cache-Control: must-understand, no-store
200              
201             =head2 no_cache
202              
203             This takes a boolean value. When the value is true, this property is set if it does not already exist, and if false, it is removed.
204              
205             If no value is provided, it returns true if the property is already set and false if it is not.
206              
207             The C<no-cache> response directive indicates that the response can be stored in caches, but the response must be validated with the origin server before each reuse, even when the cache is disconnected from the origin server.
208              
209             Cache-Control: no-cache
210              
211             This is used in request and in response.
212              
213             =head2 no_store
214              
215             This takes a boolean value. When the value is true, this property is set if it does not already exist, and if false, it is removed.
216              
217             If no value is provided, it returns true if the property is already set and false if it is not.
218              
219             The C<no-store> response directive indicates that any caches of any kind (private or shared) should not store this response.
220              
221             Cache-Control: no-store
222              
223             This is used in request and in response.
224              
225             =head2 no_transform
226              
227             This takes a boolean value. When the value is true, this property is set if it does not already exist, and if false, it is removed.
228              
229             If no value is provided, it returns true if the property is already set and false if it is not.
230              
231             Some intermediaries transform content for various reasons. For example, some convert images to reduce transfer size. In some cases, this is undesirable for the content provider.
232              
233             C<no-transform> indicates that any intermediary (regardless of whether it implements a cache) shouldn't transform the response contents.
234              
235             =head2 only_if_cached
236              
237             This takes a boolean value. When the value is true, this property is set if it does not already exist, and if false, it is removed.
238              
239             If no value is provided, it returns true if the property is already set and false if it is not.
240              
241             The client indicates that cache should obtain an already-cached response. If a cache has stored a response, it's reused.
242              
243             =head2 params
244              
245             Returns the L<array object|Module::Generic::Array> used by this header field object containing all the properties set.
246              
247             =head2 private
248              
249             This takes a boolean value. When the value is true, this property is set if it does not already exist, and if false, it is removed.
250              
251             If no value is provided, it returns true if the property is already set and false if it is not.
252              
253             The C<private> response directive indicates that the response can be stored only in a private cache (e.g. local caches in browsers).
254              
255             Cache-Control: private
256              
257             =head2 property
258              
259             Sets or gets an arbitrary property.
260              
261             $h->property( community => 'UCI' );
262             my $val = $h->property( 'community' );
263              
264             See also L<rfc7234, section 5.2.3|https://httpwg.org/specs/rfc7234.html#rfc.section.5.2.3>
265              
266             =head2 properties
267              
268             Returns the L<hash object|Module::Generic::hash> used as a repository of properties.
269              
270             =head2 proxy_revalidate
271              
272             This takes a boolean value. When the value is true, this property is set if it does not already exist, and if false, it is removed.
273              
274             If no value is provided, it returns true if the property is already set and false if it is not.
275              
276             The C<proxy-revalidate> response directive is the equivalent of must-revalidate, but specifically for shared caches only.
277              
278             =head2 public
279              
280             This takes a boolean value. When the value is true, this property is set if it does not already exist, and if false, it is removed.
281              
282             If no value is provided, it returns true if the property is already set and false if it is not.
283              
284             The C<public> response directive indicates that the response can be stored in a shared cache. Responses for requests with Authorization header fields must not be stored in a shared cache; however, the public directive will cause such responses to be stored in a shared cache.
285              
286             Cache-Control: public
287              
288             =head2 s_maxage
289              
290             The C<s-maxage> response directive also indicates how long the response is fresh for (similar to max-age) — but it is specific to shared caches, and they will ignore max-age when it is present.
291              
292             Cache-Control: s-maxage=604800
293              
294             =head2 stale_if_error
295              
296             The C<stale-if-error> response directive indicates that the cache can reuse a stale response when an origin server responds with an error (500, 502, 503, or 504).
297              
298             Cache-Control: max-age=604800, stale-if-error=86400
299              
300             =head2 stale_while_revalidate
301              
302             The C<stale-while-revalidate> response directive indicates that the cache could reuse a stale response while it revalidates it to a cache.
303              
304             Cache-Control: max-age=604800, stale-while-revalidate=86400
305              
306             =head1 AUTHOR
307              
308             Jacques Deguest E<lt>F<jack@deguest.jp>E<gt>
309              
310             =head1 SEE ALSO
311              
312             See L<rfc7234, section 5.2|https://tools.ietf.org/html/rfc7234#section-5.2>, L<rfc8246, section 2|https://tools.ietf.org/html/rfc8246#section-2> and L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control>
313              
314             L<HTTP::Promise>, L<HTTP::Promise::Request>, L<HTTP::Promise::Response>, L<HTTP::Promise::Message>, L<HTTP::Promise::Entity>, L<HTTP::Promise::Headers>, L<HTTP::Promise::Body>, L<HTTP::Promise::Body::Form>, L<HTTP::Promise::Body::Form::Data>, L<HTTP::Promise::Body::Form::Field>, L<HTTP::Promise::Status>, L<HTTP::Promise::MIME>, L<HTTP::Promise::Parser>, L<HTTP::Promise::IO>, L<HTTP::Promise::Stream>, L<HTTP::Promise::Exception>
315              
316             =head1 COPYRIGHT & LICENSE
317              
318             Copyright(c) 2022 DEGUEST Pte. Ltd.
319              
320             All rights reserved.
321              
322             This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
323              
324             =cut