| 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; |