Mojo/SAML/Document.pm

filter: Statementstmt 91.6% 22 / 24 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 8 / 8 Podpod n/a totaltotal 93.7% 30 / 32 CC 1 SCAR 0.4
CC
1
Cov
92%
BEGIN
1.3
BEGIN
1.0
BEGIN
1.0
CRAP 1.0
« Mojo/XMLSig.pm ↑ Summary Mojo/SAML.pm »
1 package Mojo::SAML::Document;
2  
3 1 ▶use Mojo::Base -base;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 1 ▶use Carp ();
Subroutine BEGIN: called CC=1 SCAR=0.0
6 1 ▶use Data::GUID ();
Subroutine BEGIN: called CC=1 SCAR=0.0
7 1 ▶use Mojo::ByteStream;
Subroutine BEGIN: called CC=1 SCAR=0.0
8 1 ▶use Mojo::Date;
Subroutine BEGIN: called CC=1 SCAR=0.0
9 1 ▶use Mojo::DOM::HTML;
Subroutine BEGIN: called CC=1 SCAR=0.0
10 1 ▶use Mojo::Template;
Subroutine BEGIN: called CC=1 SCAR=0.0
11 0 ▶use Mojo::XMLSig;
Subroutine BEGIN: called CC=1 SCAR=2.6
12  
13 use overload bool => sub {1}, '""' => sub { $_[0]->to_string }, fallback => 1;
14  
15 has [qw/sign_with_key insert_signature insert_xml_declaration/];
16 has template => sub { die 'template is required' };
17  
18 my $isa = sub {
19 my ($obj, $class) = @_;
20 Scalar::Util::blessed($obj) && $obj->isa($class);
21 };
22 sub _dom { Mojo::DOM->new->xml(1)->parse("$_[0]") }
23  
24 sub after_render {
25 my ($self, $xml) = @_;
26 if (my $sig = $self->insert_signature) {
27 $xml = $self->after_render_insert_signature($xml, $sig);
28 }
29 if (my $key = $self->sign_with_key) {
30 $xml = $self->after_render_sign($xml, $key);
31 }
32 if ($self->insert_xml_declaration) {
33 $xml = $self->after_render_insert_xml_declaration($xml);
34 }
35 return "$xml";
36 }
37  
38 sub after_render_insert_signature {
39 my ($self, $dom, $sig) = @_;
40 Carp::croak 'Signature must be a Mojo::SAML::Document::Signature'
41 unless $sig->$isa('Mojo::SAML::Document::Signature');
42  
43 $dom = _dom($dom) unless $dom->$isa('Mojo::DOM');
44 my $root = $dom->at(':root');
45 unless (@{ $sig->references }) {
46 my $id = $root->{ID};
47 unless ($id) {
48 $id = $self->get_guid;
49 $root->attr(ID => $id);
50 }
51 $sig->references([$id]);
52 }
53 $root->prepend_content("$sig");
54 return $dom;
55 }
56  
57 sub after_render_insert_xml_declaration {
58 my ($self, $xml) = @_;
59 return qq!<?xml version="1.0"?>$xml!;
60 }
61  
62 sub after_render_sign {
63 my ($self, $xml, $key) = @_;
64 return Mojo::XMLSig::sign("$xml", $key);
65 }
66  
67 sub before_render { }
68  
69 {
70 package Mojo::SAML::TemplateSandbox;
71 use Mojo::SAML::Names qw/binding nameid_format/;
72 sub tag { Mojo::ByteStream->new(Mojo::DOM::HTML::tag_to_html(@_)) }
73 }
74  
75 sub build_template {
76 my ($self, $text) = @_;
77 Mojo::Template->new(
78 autoescape => 1,
79 namespace => 'Mojo::SAML::TemplateSandbox',
80 prepend => 'my $self = shift',
81 )->parse($text);
82 }
83  
84 sub get_guid { Data::GUID->guid_string }
85 sub get_instant { Mojo::Date->new->to_datetime }
86  
87 sub to_string {
88 my $self = shift;
89 $self->before_render;
90 my $output = $self->template->process($self);
91 $output = $self->after_render($output);
92 return Mojo::ByteStream->new($output);
93 }
94  
95 sub to_string_deflate {
96 require Compress::Raw::Zlib;
97 my $zlib = Compress::Raw::Zlib::Deflate->new;
98 my $string = shift->to_string;
99 my $compressed;
100 Carp::croak 'Compress failed'
101 unless $zlib->deflate($string, $compressed) == Compress::Raw::Zlib::Z_OK();
102 Carp::croak 'Compress failed'
103 unless $zlib->flush($compressed) == Compress::Raw::Zlib::Z_OK();
104  
105 return Mojo::Util::b64_encode($compressed, '');
106 }
107  
108 1;
109  
110 =head1 NAME
111  
112 Mojo::SAML::Document - Base class for classes representing and generating XML snippets
113  
114 =head1 SYNOPSIS
115  
116 # use as a base class
117 package Mojo::SAML::Document::MyDocument;
118 use Mojo::Base 'Mojo::SAML::Document';
119  
120 has template => sub { shift->build_template(<<'TEMPLATE') };
121 <SomeXML>...</SomeXML>
122 TEMPLATE
123  
124 # direct usage
125 my $doc = Mojo::SAML::Document->new;
126 $doc->template($doc->build_template(<<'TEMPLATE'));
127 <SomeXML>...</SomeXML>
128 TEMPLATE
129 my $output = $doc->to_string;
130 my $ouput = "$doc";
131  
132 =head1 DESCRIPTION
133  
134 L<Mojo::SAML::Document> is a base class for classes that represent XML snippets and can be used to generate those snippets from data.
135 These objects stringify to their XML representation (based on their L</template>) making them easily composable.
136  
137 While intended as a base class, it can also be used directly for one-off snippets when setting the L</template> manually.
138  
139 =head1 ATTRIBUTES
140  
141 L<Mojo::SAML::Document> inherits all of the attributes from L<Mojo::Base> and implements the following new ones.
142  
143 =head2 insert_signature
144  
145 Optional.
146 A signature document, likely an instance of L<Mojo::SAML::Docuemnt::Signature> to insert.
147 See later methods for more description.
148  
149 =head2 insert_xml_declaration
150  
151 Optional, undefined (false) by default.
152 If true the resulting rendered document will contain an XML declaration.
153 This should only be set (if at all) on the outermost document snippet.
154 See later methods for more description.
155  
156 =head2 sign_with_key
157  
158 Optional.
159 A key to sign the document, likely an instance of L<Crypt::OpenSSL::RSA>.
160 See later methods for more description.
161  
162 =head2 template
163  
164 An instance of L<Mojo::Template> used to generate the XML.
165 The default implementation dies if not set.
166 Commonly, subclasses will overload this to provide an appropriate template for the class.
167  
168 =head1 METHODS
169  
170 L<Mojo::SAML::Document> inherits all of the methods from L<Mojo::Base> and implements the following new ones.
171  
172 =head2 after_render
173  
174 $xml = $doc->after_render($xml);
175  
176 Called during rendering (see L</to_string>) after the document is rendered but before it is wrapped in a L<Mojo::ByteStream> and returned.
177 It is provided here to allow overriding by specific document types.
178 This method can be used to post-process the rendered document.
179  
180 The default implementation of this method calls L</after_render_insert_signature> if a signature is given in L</insert_signature>.
181 If then calls L</after_render_sign> if a key is given in L</sign_with_key>.
182 Finally it calls L</after_render_insert_xml_declaration> if L</insert_xml_declaration> is true.
183  
184 This default implementation allows any document to be signed during rendering by giving an appropriate document (likely a L<Mojo::SAML::Document::Signature>) and a key (an instance of L<Crypt::OpenSSL::RSA>).
185 Note that you probably only want to sign once on a full document render (not once per snippet) so keep that in mind when composing your snippets.
186  
187 =head2 after_render_insert_signature
188  
189 $xml = $doc->after_render_insert_signature($xml, $signature);
190  
191 Called during the default L</after_render> implementation.
192 It is provided here to allow overriding the insert by specific documents types.
193 Note that this default implementation requires a L<Mojo::SAML::Document::Sigature> object when called and actually returns a L<Mojo::DOM> reprenting the parsed form of its input.
194  
195 Note that this is probably not that useful to call directly.
196  
197 =head2 after_render_insert_xml_declaration
198  
199 $xml = $doc->after_render_insert_xml_declaration($xml);
200  
201 Called during the default L</after_render> implementation.
202 It is provided here to allow overriding the insert by specific documents types.
203 It prepends a standard XML declaration to the passed-in document.
204  
205 Note that this is probably not that useful to call directly.
206  
207 =head2 after_render_sign
208  
209 $xml = $doc->after_render_sign($xml, $key);
210  
211 Called during the default L</after_render> implementation.
212 It is provided here to allow overriding the signing process by specific documents types.
213 Calls L<Mojo::XMLSig/sign> with the XML payload and the given key.
214  
215 Note that this is probably not that useful to call directly.
216  
217 =head2 before_render
218  
219 $doc->before_render();
220  
221 Called during rendering (see L</to_string>) before the document is rendered.
222 It is provided here to allow overriding by specific document types.
223 This method can be used to pre-process and/or validate the object before rendering.
224 The return value is ignored.
225  
226 The default implementation does nothing.
227  
228 =head2 build_template
229  
230 has template => sub { shift->build_template($string) };
231  
232 Builds an instance of L<Mojo::Template> from a given string.
233 This is especially useful in the L</template> initializer.
234  
235 The resulting template sets C<autoescape> to true which promotes good xml escaping.
236 It configures the template to shift off the invocant as C<$self> for use during the template.
237 (Note that during L</to_string> or stringification no arguments are passed to the template rendering, so this is very useful.)
238  
239 Finally, it sets C<namespace> to C<Mojo::SAML::TemplateSandbox>.
240 This namespace is prepopulated with L<Mojo::SAML::Names/binding> and L<Mojo::SAML::Names/nameid_format> functions as well as a version of L<Mojolicious::Plugins::TagHelpers/tag>.
241  
242 =head2 get_guid
243  
244 my $guid = $doc->get_guid;
245  
246 Generates a GUID using L<Data::GUID/guid_string>.
247  
248 =head2 get_instant
249  
250 my $instant = $doc->get_instant;
251  
252 Generates an L<"RFC 3339"/http://tools.ietf.org/html/rfc3339> datetime representing the current time using L<Mojo::Date/to_datetime>.
253  
254 =head2 to_string
255  
256 my $xml = $doc->to_string;
257  
258 Generates a string representation of the document.
259 First calls L</before_render> for possible validation.
260 Then renders the L</template> using L<Mojo::Template/process> passing the document itself into the template.
261 Then it post-processes the document by calling L</after_render> with the rendered result.
262 Finally that result is wrapped in a L<Mojo::ByteStream> object (to prevent later rendering from xml escaping) and returned.
263  
264 =head2 to_string_deflate
265  
266 Calls L</to_string> but further DEFLATE encodes and base64 encodes the result.
267 This is useful when the document is going to passed as a query parameter.
268 Note that when you do this, you probably don't want to include a signature nor sign it as in this case there is a different signing procedure.
269  
270 =head1 OPERATORS
271  
272 L<Mojo::SAML::Document> overloads the following operators.
273  
274 =head2 bool
275  
276 my $bool = !!$doc;
277  
278 Always true.
279  
280 =head2 stringify
281  
282 my $str = "$doc";
283  
284 Alias for L</"to_string">.
285  
« Mojo/XMLSig.pm ↑ Summary Mojo/SAML.pm »