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

filter: Statementstmt 0.0% 0 / 213 Branchbran 0.0% 0 / 92 Conditioncond 0.0% 0 / 48 MC/DCmcdc 0.0% 0 / 27 Subroutinesub 0.0% 0 / 35 Podpod 0.0% 0 / 24 totaltotal 0.0% 0 / 439 CC 47 SCAR 35.6
CC
47
Cov
0%
key
132.0
store
56.0
snapshot_store
56.0
CRAP 35.3
1 # ex:ts=8 sw=4:
2 # $OpenBSD$
3 #
4 # Copyright (c) 2026 Dick Olsson <hi@dickolsson.com>
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 # App::FuguVM::DiskCache - cache of installed OpenBSD disks.
21 #
22 # An OpenBSD installation under TCG emulation costs tens of minutes.
23 # This module keeps the result: a pristine, compacted copy of the disk,
24 # taken the moment the installer finished. Later runs use that copy as
25 # the backing image of a throwaway overlay.
26 #
27 # The module caches the disk. App::FuguVM::Miniroot caches the install
28 # media that produced it. Neither is a cache of the other.
29  
30 package App::FuguVM::DiskCache;
31 our $VERSION = '0.3.1';
32  
33 use Digest::SHA ();
34 use Fcntl qw(:flock);
35 use File::Path qw(remove_tree);
36 use Fugu::File;
37 use Fugu::Log;
38 use Fugu::Proxy;
39 use Fugu::Timeout;
40 use App::FuguVM::Console;
41 use App::FuguVM::Disk;
42  
43 use constant {
44 BASE_NAME => 'base.qcow2',
45 META_NAME => 'meta.json',
46 INSTALLED_DIR => 'installed',
47 SNAPSHOT_DIR => 'snapshots',
48 TEMP_PREFIX => '.tmp.',
49 LOCK_PREFIX => '.lock.',
50 LOCK_TIMEOUT => 3600,
51 GENERATION_FILE => 'cache-generation',
52 INSTALL_SCRIPT => 'install.exp',
53 AUTOINSTALL_SCRIPT => 'autoinstall.exp',
54 KEY_HASH_LENGTH => 8,
55 MAX_SNAPSHOT_NAME => 128,
56 };
57  
58 sub new ( $class, $cache_dir )
59 {
60 my $self =
61 bless { cache_dir => Fugu::File->expand_tilde($cache_dir), },
62 $class;
63  
64 return $self;
65 }
66  
67 # $self->installed_dir:
68 # Return the directory that holds every cached entry.
69 sub installed_dir ($self)
70 {
71 return "$self->{cache_dir}/" . INSTALLED_DIR;
72 }
73  
74 # $self->entry_dir($key):
75 # Return the directory of one cached entry.
76 sub entry_dir ( $self, $key )
77 {
78 return $self->installed_dir . "/$key";
79 }
80  
81 # $self->base_path($key):
82 # Return the absolute path of the base image of an entry. The
83 # method does not check that the image exists.
84 sub base_path ( $self, $key )
85 {
86 return $self->entry_dir($key) . '/' . BASE_NAME;
87 }
88  
89 # $self->key($vm_config):
90 # Derive the cache key for a VM configuration:
91 # <version>-<arch>-<hash8>. The hash covers each input that
92 # shapes an installed disk, and it covers nothing else. Thus
93 # memory and port changes keep hitting the same entry. The
94 # record follows the install mode, because each mode shapes the
95 # disk with different inputs:
96 #
97 # expect version, arch, disk_size, the digest of
98 # install.exp, the digest of the generation file
99 # autoinstall version, arch, disk_size, the digest of
100 # autoinstall.exp, the digest of the response file,
101 # the digest of the generation file
102 # import version, arch, the digest of the generation file
103 #
104 # An import runs no script, and its overlay inherits the virtual
105 # size of the base. Thus the import record holds no script digest
106 # and no disk_size, and an imported entry survives a change to a
107 # shipped expect script. Return undef when an input cannot be
108 # read. Then the caller has no key and thus no caching.
109 sub key ( $self, $vm_config )
110 {
111 if ( !defined $vm_config->{arch} ) {
112 warn "Cannot derive a cache key without an architecture\n";
113 return;
114 }
115  
116 my $version = _sanitize( $vm_config->{version} // '' );
117 my $arch = _sanitize( $vm_config->{arch} );
118 my $mode = $vm_config->{install_mode} // 'expect';
119  
120 my @inputs = ( "version=$version", "arch=$arch" );
121  
122 push @inputs, 'disk_size=' . ( $vm_config->{disk_size} // '' )
123 if $mode ne 'import';
124 push @inputs, "install_mode=$mode";
125  
126 # The verify switch shapes an installed disk: the installer of
127 # the expect mode reads it, and every install boots a miniroot
128 # that the host fetched under it. An import runs no install, so
129 # the switch does not shape an imported entry.
130 push @inputs, 'verify=' . ( ( $vm_config->{verify} // 1 ) ? 1 : 0 )
131 if $mode ne 'import';
132  
133 if ( $mode ne 'import' ) {
134 my $script =
135 $mode eq 'autoinstall'
136 ? AUTOINSTALL_SCRIPT
137 : INSTALL_SCRIPT;
138 my $digest =
139 $self->_file_digest( $self->_driver_script($script),
140 $script );
141 return if !defined $digest;
142 push @inputs, "install=$digest";
143 }
144  
145 if ( $mode eq 'autoinstall' ) {
146 my $digest = $self->_file_digest(
147 $vm_config->{autoinstall},
148 'the autoinstall response file'
149 );
150 return if !defined $digest;
151 push @inputs, "response=$digest";
152 }
153  
154 my $generation =
155 $self->_file_digest( $self->_generation_file, GENERATION_FILE );
156 return if !defined $generation;
157 push @inputs, "generation=$generation";
158  
159 my $hash = Digest::SHA::sha256_hex( join( "\n", @inputs ) );
160  
161 return "$version-$arch-" . substr( $hash, 0, KEY_HASH_LENGTH );
162 }
163  
164 # $self->_file_digest($path, $what):
165 # Hash the content of one key input. The record holds the digest
166 # and not the content. Thus the joined record stays free of
167 # newlines, and an input value cannot forge the delimiter. Return
168 # undef, with a warning that names $what, when the file cannot be
169 # read.
170 sub _file_digest ( $, $path, $what )
171 {
172 if ( !defined $path ) {
173 warn "Cannot locate $what for cache key\n";
174 return;
175 }
176  
177 my $content = Fugu::File->read($path);
178 return if !defined $content;
179  
180 return Digest::SHA::sha256_hex($content);
181 }
182  
183 # $self->lookup($key):
184 # Return { base => path, meta => hashref, dir => path } for a
185 # complete entry, or undef otherwise. A half-written entry is a
186 # miss, not an error. The caller falls back to a full
187 # installation.
188 sub lookup ( $self, $key )
189 {
190 return if !defined $key;
191  
192 my $dir = $self->entry_dir($key);
193 my $base = "$dir/" . BASE_NAME;
194 return if !-f $base;
195  
196 my $meta = Fugu::File->read_json( "$dir/" . META_NAME );
197 return if !defined $meta;
198  
199 return {
200 key => $key,
201 dir => $dir,
202 base => $base,
203 meta => $meta,
204 };
205 }
206  
207 # $self->store($key, $disk_path, $meta):
208 # Publish $disk_path as the cached base image for $key. The
209 # method builds the entry whole in a sibling temporary directory.
210 # Then it publishes the entry with a rename of that directory.
211 # Thus no reader sees the base image of one installation beside
212 # the metadata of another installation. Such a mismatch would
213 # look live. It would then wedge every later boot with a root
214 # password that does not open the image.
215 #
216 # Entries are write-once: a rename onto a populated directory
217 # fails with ENOTEMPTY, and the existing entry wins. Return the
218 # base image path, or undef on any failure.
219 sub store ( $self, $key, $disk_path, $meta = {} )
220 {
221 return if !defined $key;
222  
223 if ( !-f $disk_path ) {
224 warn "Cannot cache missing disk image: $disk_path\n";
225 return;
226 }
227  
228 Fugu::File->ensure_dir( $self->installed_dir ) or return;
229  
230 my $target = $self->entry_dir($key);
231 if ( -e "$target/" . BASE_NAME ) {
232 Fugu::Log->default->warning(
233 'Image cache entry already exists: %s', $key );
234 return;
235 }
236  
237 my $built = Fugu::File->atomic_dir(
238 $target,
239 sub ($tmp) {
240 my $base = "$tmp/" . BASE_NAME;
241 return 0
242 if !App::FuguVM::Disk->convert( $disk_path, $base );
243  
244 chmod 0400, $base or do {
245 Fugu::Log->default->warning(
246 'Cannot set permissions on %s: %s',
247 $base, $! );
248 return 0;
249 };
250  
251 my %record = (
252 %$meta,
253 key => $key,
254 created_at => time,
255 );
256  
257 # The record carries the guest root password, so
258 # the file gets its mode before its content
259 return Fugu::File->write_json( "$tmp/" . META_NAME,
260 \%record, mode => 0600 ) ? 1 : 0;
261 } );
262 return if !defined $built;
263  
264 return "$target/" . BASE_NAME;
265 }
266  
267 # $self->lock_entry($key, $timeout):
268 # Return an open, exclusively locked handle on the lock file of
269 # $key. The caller holds the lock until the handle closes or the
270 # process exits, so a stale lock file blocks nothing. Return
271 # undef when the deadline elapses, and undef when the file cannot
272 # open.
273 #
274 # The lock serializes the first population of one entry across
275 # every project that shares the cache directory. It does not
276 # replace the write-once rule of store: a run that lost the lock
277 # to the deadline still cannot publish a second entry.
278 #
279 # The file name starts with a dot, so it cannot collide with an
280 # entry. list reads only a directory whose name has no leading
281 # dot. sweep_temp removes only a '.tmp.' directory.
282 sub lock_entry ( $self, $key, $timeout = LOCK_TIMEOUT )
283 {
284 return if !defined $key;
285  
286 Fugu::File->ensure_dir( $self->installed_dir ) or return;
287  
288 my $path = $self->installed_dir . '/' . LOCK_PREFIX . $key;
289 open my $fh, '>>', $path or do {
290 Fugu::Log->default->warning( 'Cannot open %s: %s', $path, $! );
291 return;
292 };
293  
294 my $locked =
295 Fugu::Timeout::bounded( $timeout, sub { flock $fh, LOCK_EX } );
296 return $fh if $locked;
297  
298 close $fh;
299 return;
300 }
301  
302 # $self->list:
303 # Return every complete entry, newest first, as
304 # { key, dir, base, size, created_at, meta, snapshots }
305 sub list ($self)
306 {
307 my @entries;
308 my $installed = $self->installed_dir;
309 return \@entries if !-d $installed;
310  
311 opendir my $dh, $installed or return \@entries;
312 my @keys = grep { !/^\./ && -d "$installed/$_" } readdir $dh;
313 closedir $dh;
314  
315 for my $key ( sort @keys ) {
316 my $entry = $self->lookup($key) or next;
317 $entry->{size} = Fugu::Proxy::Cache->dir_size( $entry->{dir} );
318 $entry->{created_at} = $entry->{meta}{created_at};
319 $entry->{snapshots} = $self->_snapshot_names($key);
320 push @entries, $entry;
321 }
322  
323 return [
324 sort { ( $b->{created_at} // 0 ) <=> ( $a->{created_at} // 0 ) }
325 @entries
326 ];
327 }
328  
329 # $self->key_for_path($path):
330 # Return the cache key whose entry contains $path. The path can
331 # point to a base image or to a snapshot. Return undef when $path
332 # lies outside the cache. The method lets a caller answer "which
333 # cached image is this disk built on?".
334 sub key_for_path ( $self, $path )
335 {
336 return if !defined $path;
337  
338 my $installed = $self->installed_dir . '/';
339 return if index( $path, $installed ) != 0;
340  
341 my ($key) = split m{/}, substr( $path, length $installed ), 2;
342 return if !defined $key || $key eq '';
343  
344 return $key;
345 }
346  
347 # $self->snapshot_dir($key):
348 # Return the directory that holds the named snapshot layers of
349 # an entry.
350 sub snapshot_dir ( $self, $key )
351 {
352 return $self->entry_dir($key) . '/' . SNAPSHOT_DIR;
353 }
354  
355 # $self->snapshot_path($key, $name):
356 # Return the absolute path of a named snapshot. The method does
357 # not check that the snapshot exists.
358 sub snapshot_path ( $self, $key, $name )
359 {
360 return $self->snapshot_dir($key) . "/$name.qcow2";
361 }
362  
363 # valid_snapshot_name($name):
364 # Snapshot names become file names inside the cache. Thus they
365 # obey the same restrictions as VM names, plus a leading
366 # alphanumeric. The leading alphanumeric keeps them clear of the
367 # dot-files of the cache.
368 sub valid_snapshot_name ( $, $name )
369 {
370 return 0 if !Fugu::File->valid_name($name);
371 return 0 if length($name) > MAX_SNAPSHOT_NAME;
372 return 0 if $name !~ /^[A-Za-z0-9][\w.-]*$/;
373  
374 return 1;
375 }
376  
377 # $self->snapshot_store($key, $name, $disk_path, $meta):
378 # Publish the stopped working disk as the named snapshot layer of
379 # entry $key.
380 #
381 # The method flattens the disk onto base.qcow2 and does not copy
382 # it. A copy would carry the backing-file header of the working
383 # disk verbatim. That header is only correct while the disk hangs
384 # directly off the base. After a restore the disk hangs off a
385 # snapshot. Thus a copy would stack chains without bound. A
386 # normal second run saves the same name again. Then a copy would
387 # name itself as its own backing file. The flatten operation also
388 # keeps every snapshot a direct child of the base. Thus no
389 # snapshot is the parent of another snapshot, and the removal of
390 # one snapshot cannot orphan another.
391 #
392 # Return the snapshot path, or undef on failure.
393 sub snapshot_store ( $self, $key, $name, $disk_path, $meta = {} )
394 {
395 if ( !$self->valid_snapshot_name($name) ) {
396 warn "Invalid snapshot name: " . ( $name // '(undef)' ) . "\n";
397 return;
398 }
399  
400 my $entry = $self->lookup($key);
401 if ( !defined $entry ) {
402 warn "No cached image for $key to snapshot against\n";
403 return;
404 }
405  
406 if ( !-f $disk_path ) {
407 warn "Cannot snapshot missing disk image: $disk_path\n";
408 return;
409 }
410  
411 my $dir = $self->snapshot_dir($key);
412 Fugu::File->ensure_dir($dir) or return;
413  
414 # qemu-img writes the image, so the atomic file helpers cannot
415 # carry it. It goes through one temporary path and one rename.
416 my $target = $self->snapshot_path( $key, $name );
417 my $tmp_disk = "$target." . TEMP_PREFIX . $$;
418  
419 unlink $tmp_disk;
420  
421 if (
422 !App::FuguVM::Disk->convert(
423 $disk_path, $tmp_disk, backing => $entry->{base} ) )
424 {
425 unlink $tmp_disk;
426 return;
427 }
428  
429 chmod 0400, $tmp_disk or do {
430 warn "Cannot set permissions on $tmp_disk: $!\n";
431 unlink $tmp_disk;
432 return;
433 };
434  
435 # The root password belongs to the base image. Thus the method
436 # copies it from there and does not trust the caller.
437 my %record = (
438 %$meta,
439 key => $key,
440 name => $name,
441 root_password => $entry->{meta}{root_password},
442 created_at => time,
443 );
444  
445 # Metadata first, atomically, with the mode before the content.
446 # To save a name again is normal. A reader that catches the
447 # window sees the previous image with the new metadata. Those
448 # fields describe the base, which did not change.
449 if (
450 !Fugu::File->write_json(
451 "$dir/$name.json", \%record, mode => 0600
452 ) )
453 {
454 unlink $tmp_disk;
455 return;
456 }
457 if ( !rename $tmp_disk, $target ) {
458 warn "Cannot publish snapshot $name: $!\n";
459 unlink $tmp_disk;
460 return;
461 }
462  
463 return $target;
464 }
465  
466 # $self->snapshot_lookup($key, $name):
467 # Return { key, name, path, meta } for a snapshot whose image,
468 # metadata, and backing chain all resolve. Return undef
469 # otherwise. A snapshot whose base was removed is a miss. Thus a
470 # caller can fall back to a provision from scratch and does not
471 # fail hard.
472 sub snapshot_lookup ( $self, $key, $name )
473 {
474 return if !$self->valid_snapshot_name($name);
475  
476 my $path = $self->snapshot_path( $key, $name );
477 return if !-f $path;
478  
479 my $meta =
480 Fugu::File->read_json( $self->snapshot_dir($key) . "/$name.json" );
481 return if !defined $meta;
482  
483 my $base = $self->base_path($key);
484 return if !-f $base;
485  
486 return {
487 key => $key,
488 name => $name,
489 path => $path,
490 base => $base,
491 meta => $meta,
492 };
493 }
494  
495 # $self->snapshot_list($key):
496 # Return the sorted snapshots of an entry, as
497 # { name, path, size, created_at }
498 sub snapshot_list ( $self, $key )
499 {
500 my @snapshots;
501  
502 for my $name ( @{ $self->_snapshot_names($key) } ) {
503 my $found = $self->snapshot_lookup( $key, $name ) or next;
504 push @snapshots,
505 {
506 name => $name,
507 path => $found->{path},
508 size => ( -s $found->{path} ) // 0,
509 created_at => $found->{meta}{created_at},
510 meta => $found->{meta},
511 };
512 }
513  
514 return \@snapshots;
515 }
516  
517 # $self->snapshot_remove($key, $name):
518 # Delete a snapshot and its metadata. Removal is safe in any
519 # order: snapshots are always direct children of the base, never
520 # of each other.
521 sub snapshot_remove ( $self, $key, $name )
522 {
523 return 0 if !$self->valid_snapshot_name($name);
524  
525 my $dir = $self->snapshot_dir($key);
526 my $path = "$dir/$name.qcow2";
527 my $meta = "$dir/$name.json";
528  
529 for my $file ( $path, $meta ) {
530 next if !-e $file;
531 unlink $file or do {
532 warn "Cannot remove $file: $!\n";
533 return 0;
534 };
535 }
536  
537 return 1;
538 }
539  
540 # $self->_snapshot_names($key):
541 # Return the sorted names of the named snapshot layers under an
542 # entry.
543 sub _snapshot_names ( $self, $key )
544 {
545 my $dir = $self->snapshot_dir($key);
546 return [] if !-d $dir;
547  
548 opendir my $dh, $dir or return [];
549 my @names;
550 for my $file ( readdir $dh ) {
551 next if $file !~ /^([^.][^\/]*)\.qcow2$/;
552 push @names, $1;
553 }
554 closedir $dh;
555  
556 return [ sort @names ];
557 }
558  
559 # $self->remove($key):
560 # Delete a cached entry and everything under it. Return true when
561 # the entry is gone afterwards.
562 sub remove ( $self, $key )
563 {
564 my $dir = $self->entry_dir($key);
565  
566 # The lock file of the entry goes too, so removed keys leave no
567 # lock files behind. A holder keeps its flock on the unlinked
568 # file until it exits.
569 unlink $self->installed_dir . '/' . LOCK_PREFIX . $key;
570  
571 return 1 if !-d $dir;
572  
573 remove_tree( $dir, { safe => 0 } );
574 if ( -e $dir ) {
575 warn "Cannot remove image cache entry $key\n";
576 return 0;
577 }
578  
579 return 1;
580 }
581  
582 # $self->sweep_temp:
583 # Remove the temporary entry trees that an interrupted store left
584 # behind. This includes trees from earlier processes. Return the
585 # count of removed trees.
586 sub sweep_temp ($self)
587 {
588 return Fugu::File->sweep_temp( $self->installed_dir );
589 }
590  
591 # $self->_driver_script($name):
592 # Return the shipped expect script whose bytes go into the cache
593 # key. The path resolves through App::FuguVM::Console. Thus it is
594 # always the same file that the console methods would execute.
595 sub _driver_script ( $, $name )
596 {
597 return App::FuguVM::Console->script_path($name);
598 }
599  
600 # $self->_generation_file:
601 # Locate share/fuguvm/cache-generation. Its contents rotate the
602 # cache key when the install driver changes in ways that the
603 # install.exp hash cannot see.
604 sub _generation_file ($)
605 {
606 return Fugu::File->share_path(
607 'share/fuguvm/' . GENERATION_FILE,
608 from => __FILE__,
609 dist => 'App-FuguVM'
610 );
611 }
612  
613 sub _sanitize ($value)
614 {
615 $value =~ s/[^\w.]/_/g;
616 return $value;
617 }
618  
619 1;