blib/lib/App/FuguVM/Remote.pm untested

filter: Statementstmt 0.0% 0 / 141 Branchbran 0.0% 0 / 50 Conditioncond 0.0% 0 / 23 MC/DCmcdc 0.0% 0 / 15 Subroutinesub 0.0% 0 / 17 Podpod 0.0% 0 / 10 totaltotal 0.0% 0 / 256 CC 26 SCAR 42.0
CC
26
Cov
0%
_entries
182.0
put
42.0
get
20.0
CRAP 66.4
1 # ex:ts=8 sw=4:
2 # $OpenBSD$
3 #
4 # Copyright (c) 2026 Dick Olsson <hi@senzilla.io>
5 #
6 # Permission to use, copy, modify, and distribute this software for any
7 # purpose with or without fee is hereby granted, provided that the above
8 # copyright notice and this permission notice appear in all copies.
9 #
10 # THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11 # WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 # MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13 # ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 # WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 # ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 # OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17  
18 use v5.36;
19  
20 package App::FuguVM::Remote;
21 our $VERSION = '0.3.1';
22  
23 use File::Basename;
24 use File::Find ();
25 use Fugu::File;
26 use Fugu::Log;
27 use Fugu::SSH;
28  
29 # App::FuguVM::Remote - the remote side of one running guest.
30 #
31 # The module owns the Fugu::SSH object, the argument quoting, the
32 # local walk, and the publish order. Thus App::FuguVM::CLI keeps thin
33 # command bodies, and one module holds the session timeout.
34  
35 use constant {
36  
37 # Seconds. Fugu::SSH bounds the connect and the channel read
38 # with this one value. The value holds a guest build and a
39 # large transfer, and it still ends a hang.
40 SSH_TIMEOUT => 3600,
41  
42 # Bytes, for one file. write_file and read_file each hold a
43 # file in memory, so the cap fails closed.
44 MAX_TRANSFER_SIZE => 64 * 1024 * 1024,
45  
46 # Paths for each batched remote command, so no command line
47 # grows too long.
48 BATCH_PATHS => 100,
49 };
50  
51 # The caller must give a host and a port. A missing value is a
52 # programming error, because App::FuguVM::CLI resolves both before it
53 # builds the object.
54 sub new ( $class, %args )
55 {
56 die "App::FuguVM::Remote->new needs a host\n"
57 if !defined $args{host};
58 die "App::FuguVM::Remote->new needs a port\n"
59 if !defined $args{port};
60  
61 my $self = bless {
62 host => $args{host},
63 port => $args{port},
64 ssh => Fugu::SSH->new(
65 host => $args{host},
66 port => $args{port},
67 user => 'root',
68 timeout => SSH_TIMEOUT,
69 ),
70 }, $class;
71  
72 return $self;
73 }
74  
75 # $class_or_self->quote_argv(@argv):
76 # Return one remote command string. Each word gets single
77 # quotes, and a single quote inside a word becomes the '\''
78 # form. An empty word becomes ''. The words join with one
79 # space. So the remote shell splits the string at the word
80 # boundaries only: it expands nothing, and it globs nothing.
81 sub quote_argv ( $, @argv )
82 {
83 my @words;
84 for my $word (@argv) {
85 my $quoted = $word;
86 $quoted =~ s/'/'\\''/g;
87 push @words, "'$quoted'";
88 }
89  
90 return join ' ', @words;
91 }
92  
93 # $self->run(@argv):
94 # Run one argument vector on the guest. The method returns the
95 # hash of Fugu::SSH->run_command. An empty vector is a
96 # programming error.
97 sub run ( $self, @argv )
98 {
99 die "App::FuguVM::Remote->run needs an argument vector\n"
100 if !@argv;
101  
102 return $self->{ssh}->run_command( $self->quote_argv(@argv) );
103 }
104  
105 # $self->interactive:
106 # Open an interactive session. The method returns the exit code
107 # of ssh(1).
108 sub interactive ($self)
109 {
110 return $self->{ssh}->interactive;
111 }
112  
113 # $self->put($local, $remote, %args):
114 # Copy a local file or a local directory to $remote in the
115 # guest. $remote is never a container: the content of a
116 # directory arrives under $remote, with no component for the
117 # source directory name. %args takes 'mode', the mode of each
118 # file that the method writes. Without it each file keeps its
119 # local permission bits, masked with 0777.
120 #
121 # The method creates every remote directory first, writes each
122 # file to a temporary name beside its destination, and then
123 # publishes every temporary file with mv -f. A failure removes
124 # every temporary file, so a failed run leaves no partial
125 # destination file. The method returns 1, or undef.
126 sub put ( $self, $local, $remote, %args )
127 {
128 my $entries = $self->_entries( $local, $remote, $args{mode} );
129 return if !defined $entries;
130  
131 my @dirs = grep { $_->{type} eq 'dir' } @$entries;
132 my @files = grep { $_->{type} eq 'file' } @$entries;
133  
134 return if @dirs && !$self->_mkdir( map { $_->{dest} } @dirs );
135  
136 my @temps;
137 for my $entry (@files) {
138 my $temp = "$entry->{dest}.fuguvm.$$";
139  
140 my $content = Fugu::File->read( $entry->{source} );
141 if ( !defined $content ) {
142 $self->_discard(@temps);
143 return;
144 }
145  
146 my $wrote =
147 $self->{ssh}->write_file( $temp, $content, $entry->{mode} );
148 if ( $wrote != 0 ) {
149 Fugu::Log->default->error( 'Cannot write %s to %s:%d',
150 $temp, $self->{host}, $self->{port} );
151 $self->_discard(@temps);
152 return;
153 }
154  
155 push @temps, $temp;
156 }
157  
158 if ( @files && !$self->_publish(@files) ) {
159 $self->_discard(@temps);
160 return;
161 }
162  
163 return 1;
164 }
165  
166 # $self->get($remote, $local):
167 # Copy one regular guest file to $local on the host. The method
168 # reads the whole file first, and it writes the local file
169 # atomically, mode 0644. So a failure leaves no partial local
170 # file. The method returns 1, or undef.
171 sub get ( $self, $remote, $local )
172 {
173 if ( -d $local ) {
174 Fugu::Log->default->error(
175 'The local destination is a directory: %s', $local );
176 return;
177 }
178  
179 my $content = $self->{ssh}->read_file( $remote, MAX_TRANSFER_SIZE );
180 if ( !defined $content ) {
181 Fugu::Log->default->error( 'Cannot read %s from %s:%d',
182 $remote, $self->{host}, $self->{port} );
183 return;
184 }
185  
186 Fugu::File->ensure_dir( dirname($local) ) or return;
187  
188 return Fugu::File->write_atomic( $local, $content, mode => 0644 )
189 ? 1
190 : ();
191 }
192  
193 # $self->_entries($local, $remote, $mode):
194 # Walk $local and return one sorted entry list:
195 # { type, source, dest, mode }. A directory entry carries no
196 # source and no mode. A symbolic link, a device node, a socket,
197 # a fifo, and a file above MAX_TRANSFER_SIZE each fail the whole
198 # walk, before the caller writes one byte. The method returns
199 # undef on every failure, with the reason logged.
200 sub _entries ( $self, $local, $remote, $mode = undef )
201 {
202 if ( -l $local || ( !-f $local && !-d $local ) ) {
203 Fugu::Log->default->error(
204 'Not a regular file or a directory: %s', $local );
205 return;
206 }
207  
208 my @entries;
209 my $failed;
210  
211 my $add_file = sub ( $source, $dest ) {
212 my $size = -s $source;
213 if ( $size > MAX_TRANSFER_SIZE ) {
214 Fugu::Log->default->error(
215 '%s holds %d bytes, the cap is %d',
216 $source, $size, MAX_TRANSFER_SIZE );
217 $failed = 1;
218 return;
219 }
220  
221 # The mask drops a setuid bit and a setgid bit. The
222 # --mode value of the caller can name all four digits,
223 # because the caller then asks for them.
224 my $bits = $mode // ( ( stat _ )[2] & 0777 );
225  
226 push @entries,
227 {
228 type => 'file',
229 source => $source,
230 dest => $dest,
231 mode => $bits,
232 };
233 };
234  
235 if ( -f $local ) {
236 $add_file->( $local, $remote );
237 return $failed ? undef : \@entries;
238 }
239  
240 if ( !-r $local || !-x $local ) {
241 Fugu::Log->default->error( 'Cannot enter directory: %s',
242 $local );
243 return;
244 }
245  
246 push @entries, { type => 'dir', dest => $remote };
247  
248 File::Find::find( {
249 no_chdir => 1,
250 wanted => sub {
251 return if $failed;
252 my $source = $File::Find::name;
253 return if $source eq $local;
254  
255 my $rel = substr $source, length($local) + 1;
256 my $dest = "$remote/$rel";
257  
258 if ( -l $source ) {
259 Fugu::Log->default->error(
260 'Cannot copy a symbolic'
261 . ' link: %s',
262 $source
263 );
264 $failed = 1;
265 return;
266 }
267 if ( -d $source ) {
268  
269 # Fail closed: a directory that
270 # the walk cannot enter would
271 # read as a complete copy.
272 if ( !-r $source || !-x $source ) {
273 Fugu::Log->default->error(
274 'Cannot enter'
275 . ' directory: %s',
276 $source );
277 $failed = 1;
278 $File::Find::prune = 1;
279 return;
280 }
281 push @entries,
282 { type => 'dir', dest => $dest };
283 return;
284 }
285 if ( !-f $source ) {
286 Fugu::Log->default->error(
287 'Not a regular file: %s',
288 $source );
289 $failed = 1;
290 return;
291 }
292  
293 $add_file->( $source, $dest );
294 },
295 },
296 $local
297 );
298  
299 return if $failed;
300  
301 my @sorted =
302 sort { $a->{dest} cmp $b->{dest} } @entries;
303  
304 return \@sorted;
305 }
306  
307 # $self->_mkdir(@dirs):
308 # Create every remote directory, batched under BATCH_PATHS
309 # paths for each call. The method returns 1, or undef.
310 sub _mkdir ( $self, @dirs )
311 {
312 while (@dirs) {
313 my @batch = splice @dirs, 0, BATCH_PATHS;
314 my $result =
315 $self->{ssh}
316 ->run_command( $self->quote_argv( 'mkdir', '-p', @batch ) );
317  
318 if ( $result->{exit_code} != 0 ) {
319 Fugu::Log->default->error(
320 'Cannot create directories on %s:%d: %s',
321 $self->{host}, $self->{port},
322 $result->{stderr} );
323 return;
324 }
325 }
326  
327 return 1;
328 }
329  
330 # $self->_publish(@files):
331 # Move every temporary file onto its destination, with batched
332 # mv -f commands. Each mv holds two paths, so one batch holds
333 # BATCH_PATHS / 2 moves. The method returns 1, or undef.
334 sub _publish ( $self, @files )
335 {
336 my @pairs = map { [ "$_->{dest}.fuguvm.$$", $_->{dest} ] } @files;
337  
338 while (@pairs) {
339 my @batch = splice @pairs, 0, int( BATCH_PATHS / 2 );
340 my $command = join ' && ',
341 map { $self->quote_argv( 'mv', '-f', $_->[0], $_->[1] ) }
342 @batch;
343  
344 my $result = $self->{ssh}->run_command($command);
345 if ( $result->{exit_code} != 0 ) {
346 Fugu::Log->default->error(
347 'Cannot publish files on %s:%d: %s',
348 $self->{host}, $self->{port},
349 $result->{stderr} );
350 return;
351 }
352 }
353  
354 return 1;
355 }
356  
357 # $self->_discard(@temps):
358 # Remove the temporary files that a failed put wrote, with
359 # batched rm -f commands. The removal is best effort: the
360 # caller already reports the failure that got it here.
361 sub _discard ( $self, @temps )
362 {
363 while (@temps) {
364 my @batch = splice @temps, 0, BATCH_PATHS;
365 $self->{ssh}
366 ->run_command( $self->quote_argv( 'rm', '-f', @batch ) );
367 }
368  
369 return;
370 }
371  
372 1;