File Coverage

blib/lib/cPanel/APIClient/Response/WHM1.pm
Criterion Covered Total %
statement 9 45 20.0
branch 0 18 0.0
condition 0 6 0.0
subroutine 3 8 37.5
pod 5 5 100.0
total 17 82 20.7


line stmt bran cond sub pod time code
1             package cPanel::APIClient::Response::WHM1;
2              
3 1     1   7 use strict;
  1         2  
  1         29  
4 1     1   5 use warnings;
  1         3  
  1         30  
5              
6             =encoding utf-8
7              
8             =head1 NAME
9              
10             cPanel::APIClient::Response::WHM1
11              
12             =head1 DESCRIPTION
13              
14             This class represents a response to a WHM API v1 call.
15              
16             =cut
17              
18             #----------------------------------------------------------------------
19              
20 1     1   5 use parent qw( cPanel::APIClient::Response );
  1         2  
  1         5  
21              
22             #----------------------------------------------------------------------
23              
24             =head1 METHODS
25              
26             =head2 $scalar = I->get_error()
27              
28             Returns an error message, or undef if the API call succeeded.
29             Note that this accommodates the case of a malformed API response
30             and will give appropriate generic error messages in those cases.
31              
32             This method is how you should determine whether an API call succeeded.
33              
34             =cut
35              
36             sub get_error {
37 0     0 1   my ($self) = @_;
38              
39 0           my $reason;
40              
41 0 0         if ( my $md = $self->{'metadata'} ) {
42 0 0         if ( !$md->{'result'} ) {
43 0           $reason = $md->{'reason'};
44 0 0         $reason = 'No failure “reason” given in response' if !length $reason;
45             }
46             }
47             else {
48 0           $reason = 'Missing “metadata” in response';
49             }
50              
51 0           return $reason;
52             }
53              
54             #----------------------------------------------------------------------
55              
56             =head2 $thing = I->get_data()
57              
58             Returns the API payload.
59              
60             This “reduces” the API
61             payload when the raw payload from the API is a single-member hash
62             whose only value is an array reference. So if the API’s raw C is:
63              
64             { payload => [ 'foo', 'bar' ] }
65              
66             … then the return from this accessor will be:
67              
68             [ 'foo', 'bar' ]
69              
70             This “reduction” only happens for this particular pattern;
71             it doesn’t happen, for example, when the single-member hash’s value
72             is any other data type.
73              
74             =cut
75              
76             sub get_data {
77 0     0 1   my ($self) = @_;
78              
79 0           my $data = $self->{'data'};
80              
81             # WHM v1 customarily stores array data in a single-key hash.
82             # This serves no useful end, so it’s customary to reduce that
83             # to just the array.
84             #
85             # Note that it may end up being unhelpful in cases like
86             # the “domainuserdata” call, which nests its hash payload
87             # inside a single-member hash. But it’s longstanding practice
88             # (in CJT, anyway) to apply this reduction only when the
89             # outer hash’s single member is an array.
90             #
91 0 0 0       if ( 'HASH' eq ref($data) && 1 == keys %$data ) {
92 0           my $data2 = ( values %$data )[0];
93              
94 0 0         if ( 'ARRAY' eq ref $data2 ) {
95 0           $data = $data2;
96             }
97             }
98              
99 0           return $data;
100             }
101              
102             =head2 $data = I->get_raw_data()
103              
104             Like C but gives the verbatim data structure.
105             Intended for use in proxying situations; application logic should
106             usually prefer C.
107              
108             =cut
109              
110             sub get_raw_data {
111 0     0 1   my ($self) = @_;
112              
113 0           return $self->{'data'};
114             }
115              
116             #----------------------------------------------------------------------
117              
118             =head2 @results = I->parse_batch()
119              
120             Interprets the API response as from the C API call and returns
121             a list of instances of this class that represents the elements of that
122             response.
123              
124             =cut
125              
126             sub parse_batch {
127 0     0 1   my ($self) = @_;
128              
129 0           Cpanel::Context::must_be_list();
130              
131 0           my $class = ref $self;
132              
133 0           return map { $class->new($_) } @{ $self->get_data() };
  0            
  0            
134             }
135              
136             #----------------------------------------------------------------------
137              
138             =head2 $messages_ar = I->get_nonfatal_messages()
139              
140             Returns a reference to an array of two-member arrays, thus:
141              
142             [
143             [ info => 'Hey, by the way …' ],
144             [ warn => 'Hey, this might cause a problem …' ],
145             ]
146              
147             The first value of each two-member array is either C or C,
148             and the value is the actual message. Note that error messages are not
149             part of this structure; for that, use C.
150              
151             This follows a pattern from CJT1 and CJT2.
152              
153             =cut
154              
155             my %type_xform = qw(
156             warnings warn
157             messages info
158             );
159              
160             sub get_nonfatal_messages {
161 0     0 1   my ($self) = @_;
162              
163 0           my @messages;
164              
165 0           my $metadata = $self->{'metadata'};
166              
167 0 0 0       if ( $metadata && ( my $output = $metadata->{'output'} ) ) {
168 0           for my $type (qw( warnings messages )) {
169 0           my $msgs = $output->{$type};
170              
171 0 0         next if !$msgs;
172              
173 0 0         if ( !ref $msgs ) {
174 0           $msgs = [ split m<\n>, $msgs ];
175             }
176              
177 0 0         if ( 'ARRAY' eq ref $msgs ) {
178 0           push @messages, [ $type_xform{$type} => $_ ] for @$msgs;
179             }
180             else {
181 0           warn "Unexpected type for metadata.output.$type: $msgs";
182             }
183             }
184             }
185              
186 0           return \@messages;
187             }
188              
189             =head1 LICENSE
190              
191             Copyright 2020 cPanel, L. L. C. All rights reserved. L
192              
193             This is free software; you can redistribute it and/or modify it under the
194             same terms as Perl itself. See L.
195              
196             =cut
197              
198             1;