blib/lib/AmberDB/Base/Transact.pm untested

filter: Statementstmt 0.0% 0 / 220 Branchbran 0.0% 0 / 100 Conditioncond 0.0% 0 / 110 MC/DCmcdc 0.0% 0 / 65 Subroutinesub 0.0% 0 / 18 Podpod 0.0% 0 / 11 totaltotal 0.0% 0 / 524 CC 51 SCAR 39.9
CC
51
Cov
0%
_txn_apply_rollback
110.0
transact_end
90.0
transact_error
72.0
CRAP 54.1
1 package AmberDB::Base::Transact;
2
3 use 5.016;
4 use warnings;
5 use Carp qw(croak cluck);
6 use Fcntl qw(:flock);
7 use IO::Handle;
8 use MIME::Base64 qw(encode_base64 decode_base64);
9
10 our $VERSION = '5.26.6';
11 my $CREATED = '2026-08-11';
12
13 # Journal field separator — ASCII Record Separator (0x1E).
14 # Tab cannot be used because raw DB values contain literal tabs.
15 my $TXN_SEP = "\x1e";
16
17 # $adb->transact_error($file_path, $message);
18 # -
19 # Records a file/write error during database operations.
20 # Tags with txn_id if transaction is active.
21 # Base table write errors (matching configured .$db_ext) trigger immediate rollback
22 # unless configured with 'no_transact => 1'.
23 # Secondary files (.inx, .src, .fld, .fac, .slg, etc.) do NOT trigger rollback.
24 # -
25 sub transact_error {
26 my ( $self, $file_path, $message ) = @_;
27
28 return unless defined $file_path && length $file_path;
29 $message ||= "database write error";
30
31 my $db_ext = $self->{db_ext} || "db";
32 my $no_rollback = 1;
33
34 # Veri tablosu dosyasi kontrolu: dosya yolu .$db_ext ile bitiyorsa ana tablodur
35 if ( my ($t_name) = $file_path =~ m{([^/\\:]+)\.\Q$db_ext\E$} ) {
36 my $t_info = eval { $self->table_info($t_name) };
37 $no_rollback = ( $t_info && $t_info->{no_transact} ) ? 1 : 0;
38 }
39
40 my $error = {
41 context => $file_path,
42 message => $message,
43 txn_id => ( $self->{_txn} && $self->{_txn}->{file} ) || undef,
44 no_rollback => $no_rollback ? 1 : 0,
45 };
46
47 push @{ $self->{_error} ||= [] }, $error;
48 shift @{ $self->{_error} } if @{ $self->{_error} } > 100;
49
50 unless ( $error->{no_rollback} ) {
51 cluck "[DB_TXN_ERROR] $file_path: $message\n";
52 if ( $self->{_txn} && $self->{_txn}->{active} ) {
53 return $self->transact_rollback();
54 }
55 }
56
57 return;
58 }
59
60 # $ok = $adb->is_transact([$tableid]);
61 # ------------------------------------------------
62 # Returns 1 if transaction is active and table is eligible (not no_transact).
63 # Caches eligibility per table in $self->{_txn}->{tbl_enabled} during active transaction.
64 # ------------------------------------------------
65 sub is_transact {
66 my ( $self, $tableid ) = @_;
67
68 return 0 if $self->{_no_txn};
69
70 my $txn = $self->{_txn};
71 return 0 unless $txn && $txn->{active};
72 return 1 unless defined $tableid && length($tableid);
73
74 if ( exists $txn->{tbl_enabled}->{$tableid} ) {
75 return $txn->{tbl_enabled}->{$tableid};
76 }
77
78 my $t_info = eval { $self->table_info($tableid) };
79 my $is_enabled = ( $t_info && $t_info->{no_transact} ) ? 0 : 1;
80
81 $txn->{tbl_enabled}->{$tableid} = $is_enabled;
82 return $is_enabled;
83 }
84
85 # $adb->transact_start();
86 # -
87 # Starts a new transaction. Opens a journal file for undo logging.
88 # Applies non-blocking exclusive flock to claim ownership.
89 # Must be paired with transact_end() or transact_rollback().
90 # -
91 sub transact_start {
92 my ( $self ) = @_;
93
94 if ( $self->{_txn} && $self->{_txn}->{active} ) {
95 $self->transact_error( $self->{_txn}->{file} || "txn", "Transaction already active: $self->{_txn}->{file}" );
96 return;
97 }
98
99 # Recover orphaned transactions from previous crashes
100 $self->transact_recover();
101
102 my $journal_dir = $self->journal_dir();
103 unless ( -d $journal_dir ) {
104 $self->transact_error( $journal_dir, "Transaction directory does not exist: $journal_dir" );
105 return;
106 }
107
108 our $TXN_SEQ;
109 $TXN_SEQ = 0 unless defined $TXN_SEQ;
110 my $txn_id = time() . "_" . (++$TXN_SEQ) . "_$$";
111 my $txn_file = "$journal_dir/txn_$txn_id";
112
113 open my $fh, "+>>", $txn_file or do {
114 $self->transact_error( $txn_file, "Cannot open journal: $txn_file ($!)" );
115 return;
116 };
117 binmode $fh;
118
119 # Lock journal file non-blocking to establish active process ownership
120 unless ( flock( $fh, LOCK_EX | LOCK_NB ) ) {
121 close $fh;
122 $self->transact_error( $txn_file, "Cannot lock journal file (in use): $txn_file" );
123 return;
124 }
125
126 # Autoflush via IO::Handle for crash safety
127 $fh->autoflush(1);
128
129 $self->{_txn} = {
130 active => 1,
131 file => $txn_file,
132 fh => $fh,
133 ops => 0,
134 locks => {},
135 logged => {},
136 tbl_enabled => {},
137 };
138
139 return 1;
140 }
141
142 # Releases all record locks acquired during active transaction.
143 # ------------------------------------------------
144 sub _txn_release_locks {
145 my ( $self ) = @_;
146 return unless $self->{_txn} && ref( $self->{_txn}->{locks} ) eq "HASH";
147
148 foreach my $lock_key ( keys %{ $self->{_txn}->{locks} } ) {
149 my ( $t_id, $r_id ) = split /_/, $lock_key, 2;
150 if ( defined $t_id && defined $r_id ) {
151 $self->flock_close( $t_id, $r_id );
152 }
153 }
154 }
155
156 # $result = $adb->transact_end();
157 # -
158 # Finalizes the active transaction.
159 # If base errors occurred → rollback all operations.
160 # If no base errors → commit (journal deleted, data stays).
161 # Index errors do NOT trigger rollback.
162 # Returns: { status => "commit"|"rollback", ops => N, ... }
163 # -
164 sub transact_end {
165 my ( $self ) = @_;
166 return unless $self->{_txn};
167
168 if ( $self->{_txn}->{rolled_back} ) {
169 my $res = delete $self->{_txn}->{result};
170 delete $self->{_txn};
171 return $res;
172 }
173
174 return unless $self->{_txn}->{active};
175
176 my $txn_file = $self->{_txn}->{file};
177
178 # Only base errors (no_rollback is false) for this transaction trigger rollback
179 my @critical = grep {
180 ( $_->{txn_id} // '' ) eq $txn_file && !$_->{no_rollback}
181 } @{ $self->{_error} || [] };
182
183 if ( $self->{_txn}->{fh} ) {
184 flock( $self->{_txn}->{fh}, LOCK_UN );
185 close $self->{_txn}->{fh};
186 }
187 $self->{_txn}->{active} = 0;
188
189 if (@critical) {
190 $self->_txn_apply_rollback($txn_file) if -e $txn_file;
191 unlink $txn_file if -e $txn_file;
192
193 $self->_txn_release_locks();
194 my $txn_state = delete $self->{_txn};
195
196 return {
197 status => "rollback",
198 errors => \@critical,
199 txn_id => $txn_file,
200 ops => $txn_state->{ops},
201 };
202 }
203
204 unlink $txn_file if -e $txn_file;
205 $self->_txn_release_locks();
206 my $txn_state = delete $self->{_txn};
207
208 return {
209 status => "commit",
210 txn_id => $txn_file,
211 ops => $txn_state->{ops},
212 };
213 }
214
215 # $result = $adb->transact_commit();
216 # ------------------------------------------------
217 # Alias to transact_end() for explicit commit semantics.
218 # ------------------------------------------------
219 sub transact_commit {
220 my ( $self ) = @_;
221 return $self->transact_end();
222 }
223
224 # $result = $adb->transact_rollback();
225 # ------------------------------------------------
226 # Forces rollback regardless of error state.
227 # Use for business-logic driven rollbacks (e.g. insufficient stock).
228 # ------------------------------------------------
229 sub transact_rollback {
230 my ( $self ) = @_;
231 return unless $self->{_txn};
232
233 if ( $self->{_txn}->{rolled_back} ) {
234 return $self->{_txn}->{result};
235 }
236
237 return unless $self->{_txn}->{active};
238
239 my $txn_file = $self->{_txn}->{file};
240
241 my @critical = grep {
242 ( $_->{txn_id} // '' ) eq $txn_file && !$_->{no_rollback}
243 } @{ $self->{_error} || [] };
244
245 if ( $self->{_txn}->{fh} ) {
246 flock( $self->{_txn}->{fh}, LOCK_UN );
247 close $self->{_txn}->{fh};
248 delete $self->{_txn}->{fh};
249 }
250 $self->{_txn}->{active} = 0;
251
252 $self->_txn_apply_rollback($txn_file) if -e $txn_file;
253 unlink $txn_file if -e $txn_file;
254 $self->set_cache();
255
256 $self->_txn_release_locks();
257
258 my $ops = $self->{_txn}->{ops} || 0;
259 my $result = {
260 status => "rollback",
261 errors => \@critical,
262 txn_id => $txn_file,
263 ops => $ops,
264 };
265 $self->{_txn}->{rolled_back} = 1;
266 $self->{_txn}->{result} = $result;
267
268 return $result;
269 }
270
271 # $adb->_txn_log( $type, $tableid, $file_path, $key, $action, $old_val );
272 # ------------------------------------------------
273 # Appends one undo-log entry to the journal file.
274 # Encodes raw database value ($old_val) with Base64 for 100% binary safety.
275 # Flushes buffer and optionally calls sync (fsync) for durability.
276 # Noop if no active transaction.
277 # ------------------------------------------------
278 sub _txn_log {
279 my ( $self, $type, $tableid, $file_path, $key, $action, $old_val ) = @_;
280
281 return unless $self->{_txn} && $self->{_txn}->{active};
282 my $fh = $self->{_txn}->{fh} or return;
283 binmode $fh;
284
285 $type //= 'recs';
286 $tableid //= '';
287 $file_path //= '';
288 $key //= '';
289 $action //= 'put';
290
291 my $b64 = ( !defined $old_val || $old_val eq '__NULL__' )
292 ? '__NULL__'
293 : encode_base64( $old_val, '' );
294
295 my $ts = $self->_txn_timestamp();
296
297 print $fh join( $TXN_SEP, $ts, $type, $tableid, $file_path, $key, $action, $b64 ), "\n";
298
299 $fh->flush;
300 if ( $self->config('txn_sync') ) {
301 eval { $fh->sync };
302 }
303
304 $self->{_txn}->{ops}++;
305 return 1;
306 }
307
308 # $adb->_txn_apply_rollback($txn_file);
309 # ------------------------------------------------
310 # Reads journal in reverse order (LIFO), applies generic undo operations:
311 # Decodes Base64 payloads directly to raw binary octets and restores to DB_File.
312 # - recs (add -> delete, edit/del -> restore raw record from Base64)
313 # - index (add -> delete key, edit/del -> restore binary buffer from Base64)
314 # Independent of business logic, indexes, junk, or ramdisk configurations.
315 # Clears caches for all affected tables after rollback.
316 # ------------------------------------------------
317 sub _txn_apply_rollback {
318 my ( $self, $txn_source ) = @_;
319
320 my @lines;
321 if ( ref($txn_source) eq 'ARRAY' ) {
322 @lines = @$txn_source;
323 }
324 elsif ( ref($txn_source) && ref($txn_source) =~ /GLOB|IO/ ) {
325 seek( $txn_source, 0, 0 );
326 @lines = <$txn_source>;
327 }
328 else {
329 open my $fh, "<", $txn_source or do {
330 cluck "[DB_TXN] Cannot read journal for rollback: $txn_source ($!)\n";
331 return;
332 };
333 binmode $fh;
334 @lines = <$fh>;
335 close $fh;
336 }
337
338 my %affected_tables;
339 my %open_files;
340
341 foreach my $line ( reverse @lines ) {
342 chomp $line;
343 my ( $ts, $type, $tableid, $file_path, $key, $action, $b64 ) = split /\x1e/, $line, 7;
344 next unless defined $file_path && defined $key;
345 $affected_tables{$tableid} = 1 if $tableid;
346
347 unless ( $open_files{$file_path} ) {
348 $self->table_write($file_path) or next;
349 $open_files{$file_path} = 1;
350 }
351 my $db = $self->{_db}->{$file_path} or next;
352
353 my $is_unq = ( $file_path =~ /\.unq$/ ) ? 1 : 0;
354 my $k = ( $type eq 'recs' || $is_unq ) ? $self->utf_encode("$key") : "$key";
355
356 if ( $action eq 'add' || !defined $b64 || $b64 eq '__NULL__' ) {
357 $db->del($k);
358 }
359 else {
360 my $raw_val = decode_base64($b64);
361 $db->put( $k, $raw_val );
362 }
363 }
364
365 # Close all files touched during rollback
366 foreach my $file_path ( keys %open_files ) {
367 $self->table_close($file_path);
368 }
369
370 # Clear in-memory caches for affected tables
371 foreach my $tableid ( keys %affected_tables ) {
372 $self->clear_cache($tableid);
373 delete $self->{_auth}->{$tableid} if $self->{_auth};
374 }
375
376 return 1;
377 }
378
379 # $adb->transact_recover();
380 # ------------------------------------------------
381 # Scans journal/ directory for orphaned transaction files left by dead/crashed processes.
382 # Uses non-blocking exclusive flock to safely claim ownership without race conditions.
383 # Rolls back and removes confirmed orphaned journals.
384 # Called automatically at the start of each new transaction.
385 # ------------------------------------------------
386 sub transact_recover {
387 my ( $self ) = @_;
388
389 my $journal_dir = $self->journal_dir();
390 my @orphans = $self->dir_files( $journal_dir, "txn_*" );
391 return unless @orphans;
392
393 foreach my $orphan ( sort @orphans ) {
394 my ($pid) = $orphan =~ /[-_](\d+)$/;
395 next unless $pid;
396
397 # Skip our own active transaction file
398 next if $self->{_txn} && $self->{_txn}->{file} && $orphan eq $self->{_txn}->{file};
399
400 # Open candidate orphan journal file
401 open my $ofh, "+<", $orphan or next;
402
403 # Try to acquire exclusive non-blocking lock.
404 # If another running process owns this transaction, flock will FAIL.
405 if ( flock( $ofh, LOCK_EX | LOCK_NB ) ) {
406 # Acquired lock: No active process holds this transaction
407 # Double check PID liveness if possible
408 if ( $pid != $$ && kill( 0, $pid ) ) {
409 # Process is alive; release lock and leave alone
410 flock( $ofh, LOCK_UN );
411 close $ofh;
412 next;
413 }
414
415 # Confirmed orphan: process is dead — read journal and rollback
416 cluck "[DB_TXN] Orphan transaction rollback: $orphan\n";
417 seek( $ofh, 0, 0 );
418 my @lines = <$ofh>;
419 flock( $ofh, LOCK_UN );
420 close $ofh;
421
422 $self->_txn_apply_rollback(\@lines);
423 unlink $orphan;
424 }
425 else {
426 # File is actively locked by a living process — skip safely (race-condition free)
427 close $ofh;
428 next;
429 }
430 }
431
432 return 1;
433 }
434
435 # $ts = $adb->_txn_timestamp();
436 # ------------------------------------------------
437 # Returns epoch timestamp. Uses Time::HiRes for microsecond precision
438 # if available, otherwise falls back to time().
439 # ------------------------------------------------
440 sub _txn_timestamp {
441 my ( $self ) = @_;
442 if ( eval { require Time::HiRes; 1 } ) {
443 return sprintf( "%.6f", Time::HiRes::time() );
444 }
445 return time();
446 }
447
448 1;
449
450 __END__