This file is indexed.

/usr/share/perl5/Rinci/Transaction.pod is in librinci-perl 1.1.78-1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
package Rinci::Transaction; # just to make PodWeaver happy

# VERSION

1;
# ABSTRACT: A transactional system based on functions

__END__

=pod

=encoding UTF-8

=head1 NAME

Rinci::Transaction - A transactional system based on functions

=head1 VERSION

This document describes version 1.1.78 of Rinci::Transaction (from Perl distribution Rinci), released on 2015-09-03.

=head1 SPECIFICATION VERSION

 Rinci 1.1, protocol version 2

=head1 SPECIFICATION

This document describes a transactional system based on functions, where several
function calls participate in a single transaction. This transactional system
has the following properties:

=over 4

=item * Client/server architecture

Transaction can be performed over L<Riap>. Client can start more than one active
transaction on the server. Each transaction-management request and the function
calls are requested separately (each one is a separate Riap request).

For more details on this, see L<Riap::Transaction>.

=item * Undo/redo

Committed transactions are still recorded in the database along with its undo
information. Client can request to undo/redo the transactions. Thus the system
is also an undo/redo system.

=item * Relies on the functions for reliability/ACID properties

Server or framework provides the transaction manager (TM), but each function
acts as the resource manager (RM). It is the responsibility of the functions to
maintain ACID properties while modifying resources. For best results, each
function should be written carefully and tested extensively, and utilize a real,
robust RM (like an RDBMS to store data or a transactional filesystem layer to
read/modify files). In the absence of a real RM, some ACID properties like
isolation and consistency might be compromised. For example: one transaction TX1
modifies a file in an ordinary (i.e. non-transactional) filesystem. Another
transaction TX2 can see TX1's modification in the middle of uncommitted
transaction (violates isolation principle).

=back

=head2 How transaction works

The basic idea is that actions are performed by function calls. For each action,
TM will call the function twice. First for getting undo information, and second
for actually performing the action. The undo information can be used to perform
rollback, undo, and redo. All functions performing actions in the transaction
must be able to supply undo information.

=head2 Function requirements

Functions that participate in transaction must declare their C<tx> feature in
the metadata. In addition, function must also be idempotent.

 features => {
     ...
     tx => {v=>2},
     idempotent => 1,
 }

Function must then follow the transaction protocol, described below.

=head2 Transaction manager

The transaction manager manages transaction data and performs actions as well as
transaction management.

For the sake of examples, our TM stores data in a SQL database (like SQLite)
with the following tables:

=over 4

=item * tx

 id (PK)
 summary
 ctime (creation time)
 commit_time
 status
 last_action_id -- in-progress action ID (for tx with status=i), or last
                -- processed action (for tx with other transient statuses)

=item * do_action

 id (PK)
 tx_id (refers to tx(id))
 ctime
 sp (savepoint name, UNIQUE(sp,tx_id))
 f (function name)
 args (arguments, serialized)

=item * undo_action

 id (PK)
 tx_id (refers to tx(id))
 ctime
 f (function name)
 args (arguments, serialized)

=back

=head2 Transaction status

A transaction can have one of these statuses. They will be fully explained in
the following sections. Statuses having lowercase labels are transient statuses.
Statuses having uppercase labels are final statuses.

 i (in-progress)
 a (aborted, pending rollback to R)
 R (rolled back)
 C (committed)
 u (committed, undoing)
 v (aborted undoing, pending rollback back to C)
 U (committed, undone)
 d (committed & undone, redoing)
 e (aborted redoing, pending rollback back to U)
 X (unresolvable/error)

=head2 Transaction manager initialization

User instantiates TM. TM sets up its data directory and performs cleanup and
crash recovery.

In cleanup, TM purges unneeded data, like data for rolled back transactions or
committed transactions that have been around for too long.

In crash recovery, TM looks at all crashed transactions and resolves them
(either by performing rollback or roll forward). Crashed transactions are
in-progress (C<i>) transactions that have an in-progress action, or transactions
having one of these statuses (all the other transient statuses): C<a>, C<u>,
C<v>, C<d>, C<e>. Crash recovery will be explained in the following sections
below.

TM also can perform rollback for in-progress transactions that have been around
for too long without being committed or rolled back.

=head2 Starting transaction

User invokes C<< $tm->begin(tx_id => $tx_id) >>, providing a unique transaction
ID C<$tx_id> as identifier for the transaction. C<$tx_id> is an arbitrary string
with a length between 1 and 200 characters. User can also supply C<summary>, a
textual description for the transaction. It should not be longer than 1024
characters. TM will create an entry for the transaction in its journal:

 BEGIN;
 INSERT INTO tx (id,summary,ctime,status) VALUES ($tx_id,$summary,$now,'i')
 COMMIT;

As can be seen, initial transaction status is C<i> (in-progress).

Upon success, TM must return status 200. If transaction with that ID already
exists, TM must return status 409, unless when the existing transaction is still
on-going, in which case TM should just return 200. TM must return 400 if no
$tx_id is given. TM can also return status 412 if there are already too many
transactions being started, either globally on the server or for the particular
client.

=head2 Performing action

1) User performs action by invoking C<< $tm->action(f=>$fname, args=>$args) >>
one or several times. Transaction status must be C<i>. TM will first check
whether function exists and supports transaction. If function does not exist, or
does not support transaction, TM must return status 412.

2) TM records this action in its journal:

 BEGIN;
 INSERT INTO action (tx_id,ctime,f,args) VALUES
     ($tx_id,$now,$fname,JSON($args)); -- $act_id
 UPDATE tx SET last_action_id=$act_id WHERE id=$tx_id;
 COMMIT;

3) TM requests state checking and undo information to function, by calling the
function using the arguments C<$args> and a special argument C<<
-tx_action=>'check_state' >>. In addition TM also passes C<< -tx_v => N >> (the
protocol version) and C<< -tx_action_id => UUID >> (a unique identifier to link
between this call and the 'fix_state' call later).

There are 3 possible states that the function must decide which we are in:

=over 4

=item * fixed

This is the final, desired state. When we are already in a fixed state, function
must return status 304 (nothing to do). TM will then skip calling the function
the second time to fix state, since there is nothing to fix. For example:

 [304, "File $path already exists"]      # e.g., in a create_file() function
 [304, "User $u already does not exist"] # e.g., in a delete_user() function

=item * fixable

This is where the final, desired state has not been reached, but it is possible
to reach it. When we are in this state, function must return status 200 with the
result metadata C<undo_actions>. The message should also describe what needs to
be fixed.

For example:

 [200, "Directory $path needs to be created", undef,
  {undo_actions => [rmdir => {path=>$path}]}]  # e.g. in a mkdir() function
 [200, "User $u should be created with UID $uid", undef,
  {undo_actions => [delete_user=>{user=>$u}]}] # e.g. in create_user()

=item * unfixable

This is where the final, desired state has not been reached, and it is
impossible or inappropriate for the function to fix into the fixed state. This
state is used to avoid undoing what was not fixed by the function. If we are in
this state, function should return status 412 (precondition failed).

For example:

 [412, "Path $path exists but not a symlink"] # e.g. in setup_symlink()
 [412, "User $u exists but with different UID $cur_uid (needs $uid)"]

=back

If state is unfixable, or function returns other statuses (assumed as failure),
TM stops the process and starts a rollback. C<< $tm->action() >> will return
with the function's result.

For example, let us use function C<My::setup_unix_user()> which can create a
Unix user with an empty home directory if the user has not been created. This
function utilizes several simpler functions: C<My::adduser()> to add entry to
/etc/passwd and /etc/shadow, C<My::addgroup> to add entry to /etc/group and
/etc/gshadow, C<My::mkdir> to create directory. Then there are also these
functions for the undo actions: C<My::deluser> to delete user entry in Unix
passwd database, C<My::delgroup> to delete group entry in Unix group database,
and C<My::rmdir> to remove directory.

For C<My::adduser>, the fixable state is that the user does not exist, the fixed
state is that the user exists. For C<My::deluser>, the fixable state is that
user exists (additionally with the same UID as the one created previously), the
fixed state is user does not exist, the unfixable state is user exists but with
different UID. For C<My::addgroup>, the fixable state is that group does not
exist, the fixed state is that the group exists. For C<My::delgroup>, the
fixable state is that group exists (additionally with the same GID as the one
created previously), the fixed state is group does not exist, the unfixable
state is group exists but with different GID. For C<My::mkdir>, the fixable
state is path does not exist, the fixed state is directory exists, and unfixable
state is path exists but is not a directory. For C<My::rmdir>, the fixable state
is directory exists and empty, the fixed state is path does not exist, the
unfixable state is path exists but not a directory or directory is not empty.

The C<undo_actions> must be an array containing action information, in reverse
order. Each action is a two-element array C<[$fname, $args]> where C<$fname> is
name of a function (not necessarily the same function) and C<$args> its call
arguments.

For example, if user invokes C<< $tm->action(f=>'My::setup_unix_user',
args=>{user=>'bob'}) >> and user C<bob> does not exist yet, function will
return:

 [200, "OK", undef,
  {undo_actions=>[
      ['My::deluser', {group=>'bob'}],
      ['My::delgroup', {group=>'bob'}],
      ['My::rmdir', {path=>'/home/bob'}],
  }]

4) TM records these undo actions in its journal:

 BEGIN;
 INSERT INTO undo_action (tx_id,ctime,action_id,f,args) VALUES
     ($tx_id,$now,$act_id,'My::deluser','{"group":"bob"}');    -- # $uact_id1
 INSERT INTO undo_action (tx_id,ctime,action_id,f,args) VALUES
     ($tx_id,$now,$act_id,'My::delgroup','{"user":"bob"}');    -- # $uact_id2
 INSERT INTO undo_action (tx_id,ctime,action_id,f,args) VALUES
     ($tx_id,$now,$act_id,'My::rmdir','{"path":"/home/bob"}'); -- # $uact_id3
 COMMIT;

5) If we are in fixed state, this step is skipped.

If we are in fixable state, TM calls function the second time, this time with
C<< -tx_action => 'fix_state' >>. TM also passes C<-tx_v> and C<-tx_action_id>
with the same value as the one passed previously during the 'check_state' call.
Function must perform action to fix the state into the fixed state. In our
example, C<setup_unix_user()> should create user and group C<bob>, and creates
an empty directory C</home/bob>.

Function must return status 200 on success. Other status will be interpreted as
failure, in which case TM will stop the process and starts rollback. C<<
$tm->action() >> will return with the function's result.

Note: During the 'check_state' phase in step 3, function can also optionally
return C<do_actions> in its result metadata, for example:

 [200, "OK", undef,
  {do_actions=>[
      ['My::adduser', {group=>'bob'}],
      ['My::addgroup', {group=>'bob'}],
      ['My::mkdir', {path=>'/home/bob'}],
   undo_actions=>[
      ['My::deluser', {group=>'bob'}],
      ['My::delgroup', {group=>'bob'}],
      ['My::rmdir', {path=>'/home/bob'}],
  }]

In this case, instead of calling function the second time, TM will just call the
actions provided by the function, using a nested C<< $tm->action(actions =>
$do_actions) >>. Step 4 will be skipped since each do action will provide its
own undo actions.

6) If 'fix_state' phase in step 5 succeeds, the action is finished. TM marks
this:

 BEGIN;
 UPDATE tx SET last_action_id=NULL WHERE id=$tx_id;
 COMMIT;

TM is ready to process another action.

=head3 Crash recovery

Recovery rolls back interrupted in-progress transaction. See L</"Rollback of
in-progress (status i) transaction"> for more details.

If crash happens after step 1, transaction will not be marked as crash since
C<last_action_id> has not been set and no recovery is necessary.

If crash happens after step 2 until 5, recovery will be performed by rollback.
Details of rollback is explained in L</"Rollback of in-progress (status i)
transaction">.

If crash happens after step 6, transaction will not be marked as crash since
C<last_action_id> is already unset and no recovery is necessary.

=head2 Commit

To commit transaction, user invokes C<< $tm->commit() >>. Transaction status
must be C<i> or C<a>. If transaction status is C<a>, transaction must be rolled
back instead.

TM will mark the transaction status as C<C> (committed) and
delete all entries in the C<do_action> table since they are no longer needed:

 BEGIN;
 UPDATE tx SET status='C' WHERE id=$tx_id;
 DELETE FROM do_action WHERE tx_id=$tx_id;
 COMMIT;

TM still stores the C<undo_actions> entries for some time, to allow undo (and
redo) of transactions.

If transaction status is C<a>, transaction should be rolled back instead of
committed.

Transaction status progress:

 i -> C

=head2 Rollback of in-progress (status i) transaction

If an action fails, or some other error happens, rollback will be performed by
TM. Rollback can also be started by user using C<< $tm->rollback >>. TM marks
transaction status to C<a> (aborted). This will prevent other clients trying to
add new actions to this transaction, since aborted transaction can longer accept
new actions, it can only be rolled back.

TM will then perform undo for each function, in reverse order, using the undo
actions previously recorded in C<undo_action> table. The process is similar to
performing action, except that:

=over 4

=item * After rollback succeeds, transaction status is changed to C<R>

C<R> means rolled back. These transactions can be discarded by the next cleanup
process.

=item * Undo actions are not recorded

Since we do not rollback from the rollback process, but continue it. TM still
calls function twice for each action (check_state + fix_state), but do not
bother to record the undo actions returned by function in the check_state phase
to its database.

=item * Failure in rollback step will mark transaction status as C<X>

C<X> means inconsistent/error. Transactions left in this state are probably
half-done and thus inconsistent. We give up on these transactions and the next
cleanup process can discard them.

(TODO: Should there be an option to continue to the next action anyway? But this
is not necessarily more robust or correct.)

=back

Transaction status progress:

 i -> a -> R  # successful rollback
 i -> a -> X  # failed rollback

B<Example>. Continuing our previous example, in the C<<
setup_unix_user(user=>'bob') >> action, there are 3 actions involved:

 ['My::adduser', {group=>'bob'}]
 ['My::addgroup', {group=>'bob'}]
 ['My::mkdir', {path=>'/home/bob'}]

Suppose action 1 and 2 succeed, and the following undo actions have been
recorded in C<undo_action>:

 ['My::deluser', {group=>'bob'}]  # recorded with ID $ucall_id1
 ['My::delgroup', {group=>'bob'}] # recorded with ID $ucall_id2

Suppose action 3 fails with status 500 (e.g. permission denied) and thus
rollback is started. The following is the steps that happen during rollback.
Actions will be processed in reverse order: C<$ucall_id2>, C<$ucall_id1>.

1) TM marks transaction status to aborted:

 BEGIN;
 UPDATE tx SET status='a', last_action_id=NULL WHERE id=$tx_id;
 COMMIT;

TM performs action C<My::delgroup>.

2a) TM calls C<My::delgroup()> the first time with C<< -tx_action =>
'check_state' >>. TM also passes C<< -tx_is_rollback => 1 >> for informative
purposes (some function can utilize this information to behave more robust, for
example, to avoid failing the rollback process). TM does not record the
C<undo_actions> metadata returned, but observes the C<do_actions>.

If function returns 304, step 2b is skipped and TM moves on to the next action.
If function returns 200, TM continues to step 2b. If function returns other
statuses, TM assumes rollback failure and marks transaction as C<X> and ends the
rollback process for this transaction.

2b) TM invokes C<My::delgroup()> the second time to perform the action, passing
C<< -tx_action => 'fix_state' >> and C<< -tx_is_rollback => 1 >>. Function sees
that group exists (fixable state), deletes it, return status 200.

2c) TM sets transaction's C<last_action_id> to C<$uact_id1> to mark that this
action has been processed:

 BEGIN;
 UPDATE tx SET last_action_id=$ucall_id1 WHERE id=$tx_id;
 COMMIT;

TM then continues to perform action C<My::delgroup>.

3a) Just like in step 2, TM invokes C<My::deluser()> the first time to check
state.

3b) TM invokes C<My::deluser()> to perform the action. Function sees that user
exists (fixable state), deletes it, return status 200.

3c) TM sets transaction's C<last_action_id> to C<$uact_id2> to mark that this
action has been processed:

 BEGIN;
 UPDATE tx SET last_action_id=$uact_id2 WHERE id=$tx_id;
 COMMIT;

4) TM completes the rollback process by setting transaction status to C<R>.

 BEGIN;
 UPDATE tx SET status='R' WHERE id=$tx_id;
 COMMIT;

By now the effect of the transaction has been nullified.

=head3 * Crash recovery

Recovery continues the interrupted rollback process.

If crash happens after step 1, recovery will continue the rollback process.
Rollback of aborted (status a) transaction is exactly the same as rollback of
in-progress (status i) transaction, except that C<last_action_id> is not reset.

If crash happens after step 2a-2b, C<last_action_id> is still unset, so the
process resumes at step 2a. TM does not remember whether previously before crash
the function has been executed (and cannot remember, the progress of the
execution inside the function). This is the reason why function needs to be
idempotent, because it is potentially executed twice by TM for the same action.
If function has completed deleting the group before crash, C<check_state> will
return status 304 (fixed) and TM will skip step 2b. If function has not deleted
the group before crash, C<check_state> will return status 200 (fixable) and TM
will execute step 2b.

If crash happens after step 2c/3a-3b, C<last_action_id> is set to C<$uact_id1>.
Process will resume at step 3a, since $uact_id1 has been marked as done.

If crash happens after step 3c, process will resume at step 4.

If crash happens after step 4, no recovery is necessary since transaction has
been rolled back completely.

=head2 Undo

TM allows undoing committed transaction, so the transaction system also serves
as an undo/redo system.

1) User performs undo by invoking C<< $tm->undo(tx_id => $tx_id) >>, where
C<$tx_id> is the ID of a committed transaction. If C<$tx_id> is not supplied,
the client's newest committed transaction is used. TM will first check that
transaction status is indeed C<C>.

2) TM sets transaction status to C<u> (undoing):

 BEGIN;
 UPDATE tx SET status='u' WHERE id=$tx_id;
 COMMIT;

TM then performs actions specified in the C<undo_action> table. The process is
similar to performing action, except:

=over 4

=item * After undo succeeds, transaction status is changed to C<U>

C<U> means committed but undone transaction. These transactions can be redone
back to status C<C>.

=item * Undo actions are recorded in C<do_action> table instead of C<undo_action>

=item * Failure in undo step will cause transaction to roll back to status C<C>

=back

Transaction status progress:

 C -> u -> U       # successful undo
 C -> u -> v -> C  # failed undo, rolled back to C

Continuing our previous example, suppose our C<< setup_unix_user(user=>'bob') >>
transaction has succeeded and been committed. The C<undo_action> table contains
these entries:

 ['My::deluser', {group=>'bob'}]    # recorded with ID $uact_id1
 ['My::delgroup', {group=>'bob'}]   # recorded with ID $uact_id2
 ['My::rmdir', {path=>'/home/bob'}] # recorded with ID $uact_id3

Actions will be processed in reverse order: C<$uact_id3>, C<$uact_id2>,
C<$uact_id1>.

3a) TM invokes C<My::rmdir> the first time with C<< -tx_action => 'check_state'
>>. If directory has been filled by files/subdirectories, function will return
412 ("Cannot remove home directory, non-empty") and the undo process fails with
this status. If directory exists and is still empty, function will return 200
(fixable state) and process continues.

3b) TM records the C<undo_actions> result metadata returned by function to
C<do_action> table, for redo information.

 BEGIN;
 INSERT INTO do_action (tx_id,ctime,f,args) VALUES
     ($tx_id,$now,'My::mkdir', '{"path":"/home/bob"}'); # -- $ract_id1
 COMMIT;

3c) TM invokes C<My::rmdir> the second time with C<< -tx_action => 'fix_state'
>>. Function deletes directory and return 200.

3d) TM updates C<last_action_id> to mark that this action has been processed:

 BEGIN;
 UPDATE tx SET last_action_id=$uact_id3 WHERE id=$tx_id;
 COMMIT;

TM then continue to C<$uact_id2>.

4a) TM invokes C<My::delgroup> the first time with C<< -tx_action =>
'check_state' >>.

4b) TM records undo_actions:

 BEGIN;
 INSERT INTO do_action (tx_id,ctime,f,args) VALUES
     ($tx_id,$now,'My::addgroup', '{"group":"bob"}'); # -- $ract_id2
 COMMIT;

4c) TM invokes C<My::addgroup> the second time with C<< -tx_action =>
'fix_state' >>. Function sees that group exists, deletes it, and returns 200.

4d) TM updates C<last_action_id>:

 BEGIN;
 UPDATE tx SET last_action_id=$uact_id2 WHERE id=$tx_id;
 COMMIT;

TM then continue to C<$uact_id1>.

5a) TM invokes C<My::deluser> the first time with C<< -tx_action =>
'check_state' >>.

5b) TM records undo_actions:

 BEGIN;
 INSERT INTO undo_action (tx_id,ctime,f,args) VALUES
     ($tx_id,$now,'My::adduser', '{"user":"bob"}'); # -- $ract_id3
 COMMIT;

5c) TM invokes C<My::adduser> the second time with C<< -tx_action => 'fix_state'
>>. Function sees that user exists, deletes it, and returns 200.

5d) TM updates C<last_action_id>:

 BEGIN;
 UPDATE tx SET last_action_id=$uact_id1 WHERE id=$tx_id;
 COMMIT;

6) TM completes the undo process by setting transaction status to C<U>:

 BEGIN;
 UPDATE tx SET status='U', last_action_id=NULL WHERE id=$tx_id;
 COMMIT;

=head3 Crash recovery

Recovery rolls back interrupted undoing process so that transaction status is
back to C<C> (committed). For more details, refer to L</"Rollback of undoing
(status u) transaction">.

If crash happens before finishing step 2, no recovery is necessary.

If crash happens after step 2-3c, recovery resumes from step 3a since
C<last_action_id> is still unset. That is why C<My::mkdir> needs to be
idempotent and can check state, since it is potentially executed (step 3c)
twice, before and after recovery.

If crash happens after step 3d-4c, recovery recovery resumes from step 4a since
C<last_action_id> is set to C<$uact_id3>.

If crash happens after step 4d-5c, recovery resumes from step 5a since
C<last_action_id> is set to C<$uact_id2>.

If crash happens after step 5d, recovery resumes from step 6.

=head2 Rolling back the undoing (status u) transaction

If undo fails in the middle, rollback will happen. TM marks transaction status
from C<u> to C<v>, this differentiates between an undo process in progress (in
which case recovery should continue it until status is C<U>) and a failed undo
process (in which case recovery should rolls it back to status C<C>).

TM will then perform actions from the C<do_action> table. The process is similar
to rollback of in-progress (status i) transaction, except that after rollback
succeeds, transaction status is set to C<C>.

If rollback fails, transaction status is set to C<X>.

Transaction status progress:

 u -> v -> C # rollback succeeds
 u -> v -> X # rollback fails

=head3 Crash recovery

Recovery continues the rollback process.

=head2 Redo

An undone transaction (status C<U>) can be redone back to C<C>. To do this, user
invokes C<< $tm->undo(tx_id => $tx_id) >>, where C<$tx_id> is the ID of an
undone transaction. If C<$tx_id> is not supplied, the client's newest undone
transaction is used. TM will first check that transaction status is indeed C<U>.

TM will then set transaction status to C<d> (redoing):

 BEGIN;
 UPDATE tx SET status='d' WHERE id=$tx_id;
 COMMIT;

This will prevent other clients trying to redo the same transaction. TM will
then process actions found in C<do_action> table, just like when performing
normal action.

Transaction status progress:

 U -> d -> C

=head3 Crash recovery

Recovery rolls back the redoing process. See L</"Rolling back a redoing (status
d) transaction">.

=head2 Rolling back a redoing (status d) transaction

If redo fails in the middle, rollback will happen. TM marks transaction status
from C<d> to C<e> (failed redo). This will differentiate between a redo process
in progress (in which case recovery should continue it until status is C<C>) and
a failed redo process (in which case recovery should rolls it back to status
C<U>).

TM will perform actions from the C<undo_action> table. The process is similar to
rollback of an in-progress (status i) transaction, except that after rollback
succeeds, transaction status is set to C<U>.

If rollback fails, TM will set transaction status to C<X>.

Transaction status progress:

 d -> e -> U # rollback succeeds
 d -> e -> X # rollback fails

=head3 Crash recovery

Recovery continues the rollback process.

=head2 Cleanup

Cleanup is done at TM startup and at regular intervals. TM should delete
(forget) all C and U transactions that are too old, or keep the number of those
transactions under a certain limit, according to its settings. As soon as those
transactions are deleted, they can no longer be undone/redone, since the undo
actions data has been deleted too.

The cleanup process also deletes all X transactions, since they cannot be
resolved anyway (TODO: perhaps some retry mechanism can be applied, if desired?)

Cleanup process also deletes all R transactions.

Cleanup process can also roll back any transactions with status C<i> that have
been going for too long without being committed/rolled back.

=head2 Savepoint

Basically savepoint is just a label in the C<do_action> table.

To mark a savepoint, user invokes C<< $tm->savepoint(sp_id=>$sp_id) >> where
C<$sp_id> is an arbitrary string from 1-64 characters. It must be unique within
the transaction. If the same savepoint is used, the old savepoint is replaced by
the new one.

To release (forget) a savepoint, user invokes C<<
$tm->release_savepoint(sp_id=>$sp_id) >>. It just clears the label in the
C<do_action> table.

Rollback to a savepoint is just a normal rollback process, except we stop after
finishing the undo actions of the corresponding action with the savepoint, and
transaction status is set back to C<i>. If savepoint is unknown (or marked
before any action, which is effectively the same), we rollback everything in the
transaction.

=head2 Discard

User can optionally do a cleanup of her transactions by issuing C<<
$tm->discard(tx_id=>$tx_id) >> or C<< $tm->discard_all >>. Transactions that can
be discarded are those with the final statuses: C<C>, C<U>, C<X>.

=head1 FAQ

=head2 Why is this useful?

The protocol is a pretty generic and simple way to build transactional system,
even on heterogenous, multiuser environment. If the functions are written
carefully, the system can be reliable. And even if some of the ACID properties
are compromised due to lack of real RM, the system is still useful for its
undo/redo capability.

=head2 What are the drawbacks?

The reliability of the system rests on the reliability of each involved
function. One buggy function can break the transaction.

=head2 What about non-undoable actions?

Non-undoable actions (like sending an email, permanently deleting files) should
be executed outside the scope of transaction.

=head1 SEE ALSO

Transaction behavior is largely based on PostgreSQL.

Related specifications: L<Rinci::function>, L<Riap::Transaction>

Implementations: L<Perinci::Tx::Manager>

=head1 HOMEPAGE

Please visit the project's homepage at L<https://metacpan.org/release/Rinci>.

=head1 SOURCE

Source repository is at L<https://github.com/perlancar/perl-Rinci>.

=head1 BUGS

Please report any bugs or feature requests on the bugtracker website L<https://rt.cpan.org/Public/Dist/Display.html?Name=Rinci>

When submitting a bug or request, please include a test-file or a
patch to an existing test-file that illustrates the bug or desired
feature.

=head1 AUTHOR

perlancar <perlancar@cpan.org>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by perlancar@cpan.org.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut