blib/lib/App/FileSync/Transport/Local.pm

filter: Statementstmt 97.4% 75 / 77 Branchbran 60.0% 6 / 10 Conditioncond 41.6% 5 / 12 MC/DCmcdc 0.0% 0 / 8 Subroutinesub 95.0% 19 / 20 Podpod 100% 5 / 5 totaltotal 83.3% 110 / 132 CC 13 SCAR 11.7
CC
13
Cov
87%
new
7.0
_default_server_bin
5.5
close
4.0
CRAP 3.2
« blib/lib/App/FileSync/IO.pm ↑ Summary blib/lib/App/FileSync/Config.pm »
1 package App::FileSync::Transport::Local;
2  
3 # Runs filesync-server as a child process and speaks the wire protocol over
4 # its pipes. Used by the test suite, and for a server directory that is
5 # local to the client (a NAS mount, say).
6  
7 326 ▶use App::FileSync::Platform;
Subroutine BEGIN: called CC=1 SCAR=0.0
8  
9 326 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
10 326 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
11  
12 # Not :all - this class has a close method, and autodie replaces a package's
13 # subs named after the builtins it wraps.
14 326 ▶use autodie qw(open);
Subroutine BEGIN: called CC=1 SCAR=0.0
15  
16 326 ▶use File::Basename qw(dirname);
Subroutine BEGIN: called CC=1 SCAR=0.0
17 326 ▶use File::Spec;
Subroutine BEGIN: called CC=1 SCAR=0.0
18 326 ▶use Readonly;
Subroutine BEGIN: called CC=1 SCAR=0.0
19 326 ▶use Sub::Private { mode => 'enforce' };
Subroutine BEGIN: called CC=1 SCAR=0.0
20  
21 326 ▶use App::FileSync::Args qw(named);
Subroutine BEGIN: called CC=1 SCAR=0.0
22 326 ▶use App::FileSync::Constants qw($ROLE_CLIENT $SERVER_PROGRAM);
Subroutine BEGIN: called CC=1 SCAR=0.0
23 326 ▶use App::FileSync::I18N qw(throw);
Subroutine BEGIN: called CC=1 SCAR=0.0
24 326 ▶use App::FileSync::Process;
Subroutine BEGIN: called CC=1 SCAR=0.0
25  
26 326 ▶use version; our $VERSION = version->declare('0.002.1');
Subroutine BEGIN: called CC=1 SCAR=0.0
27  
28 # How far up from this file to look for a checkout's bin/filesync-server:
29 # lib/App/FileSync/Transport is four levels, blib/lib/... five.
30 326 Readonly::Scalar my $SEARCH_DEPTH => 6;
31  
32 =encoding utf8
33  
34 =head1 NAME
35  
36 App::FileSync::Transport::Local - run the server as a local child process
37  
38 =head1 SYNOPSIS
39  
40 my $transport = App::FileSync::Transport::Local->new(
41 root => '/srv/filesync', repo => 'docs', client => 'laptop',
42 );
43 my $connection = App::FileSync::Protocol->new(in => $transport->reader, out => $transport->writer);
44 ...
45 $transport->close;
46  
47 =head1 METHODS
48  
49 =head2 new
50  
51 Purpose: start a server for one session.
52  
53 Args: C<root> (the server root), C<repo>, C<client>, optional C<role>
54 (default C<client>) and C<server_bin> (default C<FILESYNC_SERVER_BIN>, then a
55 F<bin/filesync-server> found above this module, then C<filesync-server> on
56 the PATH).
57  
58 Returns: the transport.
59  
60 Side Effects: starts C<$^X server_bin --root ... --repo ... --client ...
61 --role ...>. The child's standard error is the parent's, never the protocol
62 pipe: sharing it would put diagnostics into the protocol stream.
63  
64 Usage:
65  
66 my $transport = App::FileSync::Transport::Local->new(%args);
67  
68 =head3 EXAMPLE
69  
70 my $t = App::FileSync::Transport::Local->new(root => $root, repo => 'docs', client => 'test-1');
71 print {$t->writer} ...;
72  
73 =head3 API SPECIFICATION
74  
75 =head4 INPUT
76  
77 {
78 root => { type => 'string', min => 1 },
79 repo => { type => 'string', min => 1 },
80 client => { type => 'string', min => 1 },
81 role => { type => 'string', optional => 1 },
82 server_bin => { type => 'string', optional => 1 },
83 }
84  
85 =head4 OUTPUT
86  
87 { type => 'object', isa => 'App::FileSync::Transport::Local' }
88  
89 =head3 MESSAGES
90  
91 Key Meaning Resolution
92 transport.missing root, repo or client absent pass it
93  
94 =head3 FORMAL SPECIFICATION
95  
96 new(a) ⇒ ∃ child • argv(child) = ⟨perl, bin, --root, a.root, --repo, a.repo, --client, a.client, --role, role⟩
97  
98 =cut
99  
100 171 ▶sub new {
Subroutine new: called CC=6 SCAR=19.4
Pod documented
101 171 my $class = shift;
102 my $args = named(\@_, {
103 171 map({ $_ => { type => 'string', optional => 1 } } qw(root repo client role server_bin)),
104 }, 'Transport::Local->new');
105  
106 171 for my $required (qw(root repo client)) {
107 throw('transport.missing', { transport => 'Local', what => $required })
108 513 ▶ unless defined $args->{$required} && length $args->{$required};
Branch: 1 branch
BranchTrueFalseTotal
unless defined $args->{$required} and length $args->{$required} 0 513 513
Condition33%1/3
defined $args->{$required} and length $args->{$required}
!ll&&!rl&&r
00513
MC/DC0%0/2
defined $args->{$required} and length $args->{$required}
defined $args->{$required} length $args->{$required}
Truth table33%1/3
A and B
A= defined $args->{$required}B= length $args->{$required}
ABresult
0X0
100
111
109 }
110  
111 my @command = (
112 $^X, $args->{server_bin} || _default_server_bin(),
113 '--root', $args->{root},
114 '--repo', $args->{repo},
115 '--client', $args->{client},
116 171 ▶ '--role', $args->{role} || $ROLE_CLIENT,
Condition50%3/6
$args->{'server_bin'} || _default_server_bin()
l!l&&r!l&&!r
01710
$args->{'role'} || $App::FileSync::Transport::Local::ROLE_CLIENT
l!l&&r!l&&!r
159120
MC/DC0%0/2
$args->{'server_bin'} || _default_server_bin()
$args->{'server_bin'} _default_server_bin()
MC/DC0%0/2
$args->{'role'} || $App::FileSync::Transport::Local::ROLE_CLIENT
$args->{'role'} $App::FileSync::Transport::Local::ROLE_CLIENT
Truth table33%1/3
A || B
A= $args->{'server_bin'}B= _default_server_bin()
ABresult
1X1
011
000
Truth table66%2/3
A || B
A= $args->{'role'}B= $App::FileSync::Transport::Local::ROLE_CLIENT
ABresult
1X1
011
000
117 );
118  
119 # The child's stderr is a dup of ours. A pipe here would not be read, and
120 # the first log line would kill the server with SIGPIPE.
121 171 my $child = App::FileSync::Process::spawn(command => \@command, stderr => fileno(STDERR));
122  
123 171 return bless { %{$child} }, $class;
124 }
125  
126 =head2 reader
127  
128 Documented with L</writer> below.
129  
130 =head2 writer
131  
132 Purpose: the pipes to and from the server.
133  
134 Args: none.
135  
136 Returns: the read handle (server's stdout) or write handle (its stdin).
137  
138 Side Effects: none.
139  
140 Usage:
141  
142 my $in = $transport->reader;
143  
144 =head3 EXAMPLE
145  
146 App::FileSync::Protocol->new(in => $t->reader, out => $t->writer);
147  
148 =head3 API SPECIFICATION
149  
150 =head4 INPUT
151  
152 [ { name => 'self', type => 'object' } ]
153  
154 =head4 OUTPUT
155  
156 { type => 'object' }
157  
158 =head3 MESSAGES
159  
160 None.
161  
162 =head3 FORMAL SPECIFICATION
163  
164 reader = self.reader ; writer = self.writer
165  
166 =cut
167  
168 171 ▶sub reader {
Subroutine reader: called CC=1 SCAR=0.0
Pod documented
169 171 my ($self) = @_;
170  
171 171 return $self->{reader};
172 }
173  
174 171 ▶sub writer {
Subroutine writer: called CC=1 SCAR=0.0
Pod documented
175 171 my ($self) = @_;
176  
177 171 return $self->{writer};
178 }
179  
180 =head2 close
181  
182 Purpose: end the session's process.
183  
184 Args: none.
185  
186 Returns: 1. Repeated calls do nothing.
187  
188 Side Effects: closes both pipes (the server sees end of file) and reaps the
189 child. A server that has not exited after
190 C<$App::FileSync::Process::GRACE_SECONDS> is stopped, so a server that never
191 sees end of file cannot hang the client.
192  
193 Usage:
194  
195 $transport->close;
196  
197 =head3 EXAMPLE
198  
199 $transport->close; # safe to call twice
200  
201 =head3 API SPECIFICATION
202  
203 =head4 INPUT
204  
205 [ { name => 'self', type => 'object' } ]
206  
207 =head4 OUTPUT
208  
209 { type => 'integer', memberof => [ 1 ] }
210  
211 =head3 MESSAGES
212  
213 None.
214  
215 =head3 FORMAL SPECIFICATION
216  
217 closed' = 1 ∧ child ∉ processes'
218  
219 =cut
220  
221 171 ▶sub close { ## no critic (Subroutines::ProhibitBuiltinHomonyms, Subroutines::ProhibitAmbiguousNames) -- transport interface
Subroutine close: called CC=4 SCAR=14.0
Pod documented
222 171 my ($self) = @_;
223  
224 171 ▶ return 1 if $self->{closed}++;
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"closed"}++ 0 171 171
225  
226 # Pipe close failures mean the child already went; reaping still matters.
227 171 for my $handle (grep { defined } @{$self}{qw(writer reader)}) {
228 342 CORE::close($handle);
229 }
230 171 ▶ if ($self->{pid}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"pid"}) 171 0 171
231 171 $self->{end} = App::FileSync::Process::reap(pid => $self->{pid});
232 171 $self->{pid} = 0;
233 }
234  
235 171 return 1;
236 }
237  
238 =head2 error_text
239  
240 Purpose: what the transport itself said, for when the protocol failed.
241  
242 Args: none.
243  
244 Returns: an empty string: the local server writes its diagnostics to this
245 process's own standard error, which the user already sees.
246  
247 Side Effects: none.
248  
249 Usage:
250  
251 my $text = $transport->error_text;
252  
253 =head3 EXAMPLE
254  
255 print $transport->error_text, "\n";
256  
257 =head3 API SPECIFICATION
258  
259 =head4 INPUT
260  
261 [ { name => 'self', type => 'object' } ]
262  
263 =head4 OUTPUT
264  
265 { type => 'string' }
266  
267 =head3 MESSAGES
268  
269 None.
270  
271 =head3 FORMAL SPECIFICATION
272  
273 error_text = ""
274  
275 =cut
276  
277 0 ▶sub error_text {
Subroutine error_text: not called CC=1 SCAR=6.9
Pod documented
278 0 return '';
279 }
280  
281 # _default_server_bin
282 # Purpose: find the server program when none is configured.
283 # Entry: none.
284 # Exit: returns FILESYNC_SERVER_BIN, a bin/filesync-server found by
285 # walking up from this file (a checkout, or blib under
286 # "make test"), or the bare name (installed, on the PATH).
287 # Side effects: none.
288 171 ▶sub _default_server_bin :Private {
Subroutine _default_server_bin: called CC=5 SCAR=17.0
289 171 my $configured = $ENV{FILESYNC_SERVER_BIN};
290 171 ▶ return $configured if defined $configured && length $configured;
Branch: 1 branch
BranchTrueFalseTotal
if defined $configured and length $configured 0 171 171
Condition33%1/3
defined $configured and length $configured
!ll&&!rl&&r
17100
MC/DC0%0/2
defined $configured and length $configured
defined $configured length $configured
Truth table33%1/3
A and B
A= defined $configuredB= length $configured
ABresult
0X0
100
111
291  
292 171 my $directory = dirname(__FILE__);
293 171 for (1 .. $SEARCH_DEPTH) {
294 1015 my $candidate = File::Spec->catfile($directory, 'bin', $SERVER_PROGRAM);
295 1015 ▶ return $candidate if -f $candidate;
Branch: 1 branch
BranchTrueFalseTotal
if -f $candidate 171 844 1015
296 844 $directory = dirname($directory);
297 }
298  
299 0 return $SERVER_PROGRAM;
300 326 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
301  
302 326 1;
303  
304 __END__
« blib/lib/App/FileSync/IO.pm ↑ Summary blib/lib/App/FileSync/Config.pm »