File Coverage

blib/lib/Dancer2/Plugin/Tail.pm

Criterion	Covered	Total	%
statement	12	112	10.7
branch	0	18	0.0
condition	0	6	0.0
subroutine	4	9	44.4
pod	0	3	0.0
total	16	148	10.8

line	stmt	bran	cond	sub	pod	time	code
1							package Dancer2::Plugin::Tail;
2
3	1			1		48301	use Dancer2::Core::Types qw(Bool HashRef Str);
	1					173850
	1					9
4	1			1		2395	use Dancer2::Plugin;
	1					51559
	1					8
5
6	1			1		34828	use Carp;
	1					6
	1					44
7	1			1		483	use Session::Token;
	1					6736
	1					1045
8
9							=head1 NAME
10
11							Dancer2::Plugin::Tail - Tail a file from Dancer2
12
13
14							=head1 VERSION
15
16							Version 0.012
17
18							=cut
19
20							our $VERSION = '0.012';
21
22
23							=head1 SYNOPSIS
24
25							use Dancer2;
26							use Dancer2::Plugin::Tail;
27
28
29							=head1 DESCRIPTION
30
31							This plugin will allow you to tail a file from within Dancer2. It's designed to be unobtrusive. So, it is functional just by calling it from your scripts. Edit entries in the Dancer configuration to setup routes and activate files that may be tailed. Additionally, you may define or restrict definition of tailed files.
32
33
34							=head1 CONFIGURATION
35
36							You may specify the route to files. The plugin will only read files so Dancer2 must have read access to them. The following configuration will generate two routes: '/tail/display' and '/tail/read'.
37
38							A sample HTML page with Bootstrap and jQuery is included in the samples directory. Use it as an example to build your own page.
39
40							plugins:
41							Tail:
42							update_interval: 3000
43							stop_on_empty_cnt: 5
44							tmpdir: '/tmp'
45							display:
46							method: 'get'
47							url: '/tail/display'
48							template: 'tail.tt'
49							layout: 'nomenu.tt'
50							data:
51							method: 'get'
52							url: '/tail/read'
53							files:
54							id1:
55							heading: 'Server Access Log'
56							file: '/var/logs/access_log'
57							id2:
58							heading: 'Server Error Log'
59							file: '/var/logs/error_log'
60
61							=over
62
63							=item I
64
65							Specify an update interval. Default is 3 seconds (3000). This value is passed to your web page or window. See example that's included.
66
67
68							=item I
69
70							Specify the number of empty responses before stopping. Default is 10. This value is passed to your web page or window. See example that's included.
71
72
73							=item I
74
75							location of user generted files to tail. Default is '/tmp'.
76
77
78							=item I
79
80							Defines display settings.
81
82							=over 4
83
84							=item I
85
86							Default 'get'.
87
88
89							=item I
90
91							Route in Dancer2 to display template for tailing.
92							Default = '/tail/display'
93
94
95							=item I
96
97							Template of tail screen.
98							Default = 'tail.tt'
99
100
101							=item I
102
103							Layout of template. This is useful when opening a window to tail files.
104
105							=back
106
107							=item I
108
109							Defines file tail settings.
110
111							=over 4
112
113							=item I
114
115							Default 'get'.
116
117
118							=item I
119
120							Route in Dancer2 to tail files.
121							Default = '/tail/read'
122
123							=back
124
125							=item I
126
127							List of predefined files that can be tailed.
128
129							=over 4
130
131							=item I
132
133							Define a unique ID for this file
134
135							=over 4
136
137							=item I
138
139							This is a heading or title of the html page to be passed to the template. Use it as a short description to the file you're taiing.
140
141
142							=item I
143
144							Full path and file name to tail.
145
146							=back
147
148							B that you B have a session provider configured to dynamically tail files using this plugin. This plugin requires sessions in order to track information about user defined tailed files for the logged in user.
149							Please see L for information on how to configure session management within your application.
150
151							=back
152
153							=back
154
155							=head1 display_tail
156
157							This function displays the specified template with the data from the configuration file.
158
159
160							=head1 define_file_to_tail
161
162							A function called to dynamically define a file to tail. This is useful for launching long running applications and having their out put tailed. In general, this will generate a 32 character string that you should use to direct the output of your process. Then, Dancer2::Plugin::Tail will tail the content of this file.
163
164
165							=head1 _tail_the_file
166
167							This private function does the actual job of tailing the file.
168
169
170
171							=head1 _new_file_id
172
173							An internal functio that returns a 32 character string when called from define_file_to_tail.
174
175
176							=cut
177
178							#
179							# Accessors
180							#
181							has update_interval => (
182							is => 'ro',
183							isa => Str,
184							from_config => 1,
185							default => sub { '3000' }, # 3 second interval
186							);
187
188							has stop_on_empty_cnt => (
189							is => 'ro',
190							isa => Str,
191							from_config => 1,
192							default => sub { '10' }, # 10 Empty or 30 secs i
193							# (update_interval * stop_on_empty_cnt) = 30
194							);
195
196							has data_method => (
197							is => 'ro',
198							isa => Str,
199							from_config => 'data.method',
200							default => sub { 'get' }
201							);
202
203							has data_url => (
204							is => 'ro',
205							isa => Str,
206							from_config => 'data.url',
207							default => sub { '/tail/read' }
208							);
209
210							has display_method => (
211							is => 'ro',
212							isa => Str,
213							from_config => 'display.method',
214							default => sub { 'get' }
215							);
216
217							has display_url => (
218							is => 'ro',
219							isa => Str,
220							from_config => 'display.url',
221							default => sub { '/tail/display' },
222							);
223
224							has display_template => (
225							is => 'ro',
226							isa => Str,
227							from_config => 'display.template',
228							default => sub { 'tail.tt' },
229							);
230
231							has display_layout => (
232							is => 'ro',
233							isa => Str,
234							from_config => 'display.layout',
235							default => sub { '' },
236							);
237
238							has tmpdir => (
239							is => 'ro',
240							isa => Str,
241							from_config => 1,
242							default => sub { '/tmp' }, # write to /tmp
243							);
244
245							has files => (
246							is => 'ro',
247							isa => HashRef,
248							from_config => 1,
249							default => sub { {} }, # Empty
250							);
251
252							sub _new_file_id {
253	0			0			Session::Token->new( length => 32 )->get;
254							}
255
256							# Generate routes based on configuration settings
257							sub BUILD {
258	0			0	0		my $plugin = shift;
259	0						my $app = $plugin->app;
260
261							# Setup route to display a template for the tail
262	0						my $disp_method = $plugin->display_method;
263	0						my $disp_url = $plugin->display_url;
264
265	0						$plugin->app->log( debug => "Adding Route ");
266	0						$plugin->app->log( debug => " Method " . $disp_method);
267	0						$plugin->app->log( debug => " Regexp " . $disp_url);
268	0						$plugin->app->add_route(
269							method => $disp_method,
270							regexp => qr!$disp_url!,
271							code => \&display_tail,
272							);
273
274							# Setup a route to return json data of the file
275	0						my $data_url = $plugin->data_url;
276	0						my $data_method = $plugin->data_method;
277
278	0						$plugin->app->log( debug => "Adding Route ");
279	0						$plugin->app->log( debug => " Method " . $data_method);
280	0						$plugin->app->log( debug => " Regexp " . $data_url);
281							# Use regexp to match part of the file, then splat inside code
282	0						$plugin->app->add_route(
283							method => $data_method,
284							regexp => qr!^$data_url!,
285							code => \&_tail_the_file,
286							);
287
288							} ### BUILD
289
290
291							# Function to display template
292							sub display_tail {
293	0			0	0		my $app = shift;
294	0						my $plugin = $app->with_plugin('Tail');
295
296	0						my $error = undef;
297	0						my $params = $app->request->params;
298
299	0						$plugin->app->log( debug => "Params:");
300	0						$plugin->app->log( debug => $params );
301
302	0						my $file_id = $params->{'id'}; ### ID in config
303	0						my $curr_pos = $params->{'curr_pos'}; ### Current position to read from
304
305	0						my $tail_id = 'tail-' . $file_id; ### ID from session
306
307	0						my $file = undef;
308	0						my $tail_file = undef;
309	0						my $tail_heading = undef;
310	0						my $files = $plugin->files;
311
312	0						$plugin->app->log( debug => "Files:" );
313	0						$plugin->app->log( debug => $files );
314	0						$plugin->app->log( debug => "File id:" . $file_id );
315	0						$plugin->app->log( debug => "tail id:" . $tail_id );
316	0						$plugin->app->log( debug => "if " . $files->{$file_id} );
317	0						$plugin->app->log( debug => "file:" . $files->{$file_id}->{file} );
318	0						$plugin->app->log( debug => "heading" . $files->{$file_id}->{heading} );
319
320							# Predefined
321	0	0					if ( $files->{$file_id} ) {
322	0						$plugin->app->log( debug => "Predefined file_id=" . $file_id );
323	0						$tail_file = $files->{$file_id}->{file} ;
324	0						$tail_heading = $files->{$file_id}->{heading};
325
326							# User defined
327							} else {
328	0						$plugin->app->log( debug => "User defined tail_id=" . $tail_id );
329	0						my $file = $plugin->app->session->read($tail_id);
330	0						$tail_file = $file->{file};
331	0						$tail_heading = $file->{heading};
332							}
333
334	0	0	0				if ( ! defined $tail_file
335							\|\| $tail_file eq '' ) {
336	0						$plugin->app->log( debug => "file id " . $file_id . " is not defined." );
337	0						$error = 'The file-id you specified does not exist.' ;
338							}
339
340	0						$app->template($plugin->display_template,
341							{ id => $file_id,
342							curr_pos => $curr_pos,
343							heading => $tail_heading,
344							data_method => $plugin->data_method,
345							data_url => $plugin->data_url,
346							update_interval => $plugin->update_interval,
347							stop_on_empty_cnt => $plugin->stop_on_empty_cnt,
348							error => $error },
349							{ layout => $plugin->display_layout }) ;
350							}
351
352							# Function for a user to dynamically define a file
353							sub define_file_to_tail {
354	0			0	0		my ( $plugin, $tail ) = @_;
355
356	0						my $file_id = _new_file_id(); # Create a new file id
357
358	0	0					$tail->{heading} = ' ' if ( ! defined $tail->{heading} );
359	0	0					if ( ! defined $tail->{file} ) {
360	0						$tail->{file} = $plugin->tmpdir . '/' . $file_id ;
361							} else {
362	0	0					if ( ! -e $tail->{file} ) {
363	0						open( my $touchfile, ">>", $tail->{file} ) ;
364	0						print $touchfile " ";
365	0						close($touchfile);
366							}
367							}
368
369	0						my $tail_id = 'tail-' . $file_id ;
370
371							# Store the file name into session
372	0						$plugin->app->session->write( $tail_id => $tail );
373
374	0						return $file_id;
375							}
376
377							# Function to tail a file
378							sub _tail_the_file {
379	0			0			my $app = shift;
380	0						my $plugin = $app->with_plugin('Tail');
381
382	0						my $params = $app->request->params;
383
384	0						$plugin->app->log( debug => "In _tail_the_file " );
385
386	0						my $file_id = $params->{'id'};
387	0						my $curr_pos = $params->{'curr_pos'};
388
389	0						my $tail_id = 'tail-' . $file_id ;
390
391	0						my $files = $plugin->files;
392	0						my $file = undef;
393	0						my $tail_file = undef;
394	0						my $tail_heading = undef;
395
396	0						$plugin->app->log( debug => "files " );
397	0						$plugin->app->log( debug => $files );
398
399							# Predefined
400	0	0					if ( $files->{$file_id} ) {
401	0						$plugin->app->log( debug => "Predefined " . $file_id );
402	0						$tail_file = $files->{$file_id}->{file} ;
403	0						$tail_heading = $files->{$file_id}->{heading};
404
405							# User defined
406							} else {
407	0						$plugin->app->log( debug => "User defined " . $tail_id );
408	0						my $file = $plugin->app->session->read($tail_id);
409	0						$tail_file = $file->{file};
410	0						$tail_heading = $file->{heading};
411							}
412
413	0						$plugin->app->log( debug => "File to tail is " . $tail_file );
414	0	0	0				if ( $tail_file
415							&& -e $tail_file ) {
416
417	0						my ($output, $whence);
418
419	0						open(my $IN, '<', $tail_file); # Open file for reading
420
421							# Add header if it's 1st request
422	0	0					if ( $curr_pos < 1 ) {
423	0						$output = "$tail_file\n";
424							}
425
426							# Determine where to start reading
427	0	0					if ( $curr_pos < 0 ) {
428	0						$whence = 2; # Relative to current position
429							} else {
430	0						$whence = 1; # Absolute current position
431							}
432
433	0						seek( $IN, $curr_pos, $whence ); # Seek the place
434							# where we were last
435	0						while ( my $line = <$IN> ) { # Continue until end
436	0						$output .= $line ;
437							}
438
439	0						my $file_end = tell($IN); # Figure out the end of the file
440	0						close($IN);
441	0						$plugin->app->log( debug => "Returning JSON:" );
442	0						$plugin->app->log( debug => "new_curr_pos " . $file_end);
443	0						$plugin->app->log( debug => "interval " . $plugin->update_interval);
444	0						$plugin->app->log( debug => "output " . $output );
445
446
447							# Return JSON
448	0						$app->send_as( JSON => { new_curr_pos => $file_end,
449							interval => $plugin->update_interval,
450							output => $output } );
451
452							} else { ### if -e
453	0						$plugin->app->log( debug => "No file to tail or file does not exist " . $tail_file );
454
455							}
456							}
457
458							# setup keywords
459							plugin_keywords qw( define_file_to_tail );
460
461							=head1 AUTHOR
462
463							Hagop "Jack" Bilemjian, C<< >>
464
465
466							=head1 SUPPORT
467
468							You can find documentation for this module with the perldoc command.
469
470							perldoc Dancer2::Plugin::Tail
471
472
473							You can also look for information at:
474
475							=over
476
477							=item * Report bugs on github
478
479							L
480
481							=item * AnnoCPAN: Annotated CPAN documentation
482
483							L
484
485							=item * CPAN Ratings
486
487							L
488
489							=item * Search metaCPAN
490
491							L
492
493							=back
494
495
496							=head1 LICENSE AND COPYRIGHT
497
498							Copyright 2016-2017 Hagop "Jack" Bilemjian.
499
500							This program is free software; you can redistribute it and/or modify it
501							under the terms of the the Artistic License (2.0). You may obtain a
502							copy of the full license at:
503
504							L
505
506							Any use, modification, and distribution of the Standard or Modified
507							Versions is governed by this Artistic License. By using, modifying or
508							distributing the Package, you accept this license. Do not use, modify,
509							or distribute the Package, if you do not accept this license.
510
511							If your Modified Version has been derived from a Modified Version made
512							by someone other than you, you are nevertheless required to ensure that
513							your Modified Version complies with the requirements of this license.
514
515							This license does not grant you the right to use any trademark, service
516							mark, tradename, or logo of the Copyright Holder.
517
518							This license includes the non-exclusive, worldwide, free-of-charge
519							patent license to make, have made, use, offer to sell, sell, import and
520							otherwise transfer the Package with respect to any patent claims
521							licensable by the Copyright Holder that are necessarily infringed by the
522							Package. If you institute patent litigation (including a cross-claim or
523							counterclaim) against any party alleging that the Package constitutes
524							direct or contributory patent infringement, then this Artistic License
525							to you shall terminate on the date that such litigation is filed.
526
527							Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER
528							AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES.
529							THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
530							PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY
531							YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR
532							CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR
533							CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE,
534							EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
535
536
537
538							=head1 SEE ALSO
539
540							L
541
542							L
543
544							=cut
545
546							1; # End of Dancer2::Plugin::Tail
547