✨ Support Ctrl-C and Posix Signal cancellation #85

Author: xecrets

sdk-docs/Xecrets.Sdk.Abstractions.md

@@ -433,4 +433,51 @@ An [System.Action](https://docs.microsoft.com/en-us/dotnet/api/System.Action 'Sy
 
 #### Returns
 [System.Threading.Tasks.Task](https://docs.microsoft.com/en-us/dotnet/api/System.Threading.Tasks.Task 'System.Threading.Tasks.Task')  
-A waitable task.
+A waitable task.
+
+<a name='Xecrets.Sdk.Abstractions.IXfApiFactory'></a>
+
+## IXfApiFactory Interface
+
+A factory for creating an IXfApi instance.
+
+```csharp
+public interface IXfApiFactory
+```
+
+Derived  
+&#8627; [XfApiFactory](Xecrets.Sdk.XfApiFactory.md 'Xecrets.Sdk.XfApiFactory')
+### Methods
+
+<a name='Xecrets.Sdk.Abstractions.IXfApiFactory.Create()'></a>
+
+## IXfApiFactory.Create() Method
+
+Create an [IXfApi](Xecrets.Sdk.Abstractions.md#Xecrets.Sdk.Abstractions.IXfApi 'Xecrets.Sdk.Abstractions.IXfApi') instance without cancellation."/>
+
+```csharp
+Xecrets.Sdk.Abstractions.IXfApi Create();
+```
+
+#### Returns
+[IXfApi](Xecrets.Sdk.Abstractions.md#Xecrets.Sdk.Abstractions.IXfApi 'Xecrets.Sdk.Abstractions.IXfApi')
+
+<a name='Xecrets.Sdk.Abstractions.IXfApiFactory.Create(System.Threading.CancellationToken)'></a>
+
+## IXfApiFactory.Create(CancellationToken) Method
+
+Create an [IXfApi](Xecrets.Sdk.Abstractions.md#Xecrets.Sdk.Abstractions.IXfApi 'Xecrets.Sdk.Abstractions.IXfApi') instance.
+
+```csharp
+Xecrets.Sdk.Abstractions.IXfApi Create(System.Threading.CancellationToken ct);
+```
+#### Parameters
+
+<a name='Xecrets.Sdk.Abstractions.IXfApiFactory.Create(System.Threading.CancellationToken).ct'></a>
+
+`ct` [System.Threading.CancellationToken](https://docs.microsoft.com/en-us/dotnet/api/System.Threading.CancellationToken 'System.Threading.CancellationToken')
+
+A [System.Threading.CancellationToken](https://docs.microsoft.com/en-us/dotnet/api/System.Threading.CancellationToken 'System.Threading.CancellationToken') to cancel any long running operation.
+
+#### Returns
+[IXfApi](Xecrets.Sdk.Abstractions.md#Xecrets.Sdk.Abstractions.IXfApi 'Xecrets.Sdk.Abstractions.IXfApi')

sdk-docs/Xecrets.Sdk.XfApiFactory.md

@@ -3,79 +3,100 @@
 
 ## XfApiFactory Class
 
-Static factory methods to create an [IXfApi](Xecrets.Sdk.Abstractions.md#Xecrets.Sdk.Abstractions.IXfApi 'Xecrets.Sdk.Abstractions.IXfApi') implementation.
+Create an [IXfApi](Xecrets.Sdk.Abstractions.md#Xecrets.Sdk.Abstractions.IXfApi 'Xecrets.Sdk.Abstractions.IXfApi') instance.
 
 ```csharp
-public static class XfApiFactory
+public class XfApiFactory :
+Xecrets.Sdk.Abstractions.IXfApiFactory
 ```
 
 Inheritance [System.Object](https://docs.microsoft.com/en-us/dotnet/api/System.Object 'System.Object') 🡒 XfApiFactory
-### Methods
-
-<a name='Xecrets.Sdk.XfApiFactory.Create()'></a>
-
-## XfApiFactory.Create() Method
 
-Create an [IXfApi](Xecrets.Sdk.Abstractions.md#Xecrets.Sdk.Abstractions.IXfApi 'Xecrets.Sdk.Abstractions.IXfApi') instance with defaults.
+Implements [IXfApiFactory](Xecrets.Sdk.Abstractions.md#Xecrets.Sdk.Abstractions.IXfApiFactory 'Xecrets.Sdk.Abstractions.IXfApiFactory')
+### Constructors
 
-```csharp
-public static Xecrets.Sdk.Abstractions.IXfApi Create();
-```
+<a name='Xecrets.Sdk.XfApiFactory.XfApiFactory(string,bool,string,System.Reactive.Concurrency.IScheduler,System.Reactive.Concurrency.IScheduler)'></a>
 
-#### Returns
-[IXfApi](Xecrets.Sdk.Abstractions.md#Xecrets.Sdk.Abstractions.IXfApi 'Xecrets.Sdk.Abstractions.IXfApi')  
-An instance of [IXfApi](Xecrets.Sdk.Abstractions.md#Xecrets.Sdk.Abstractions.IXfApi 'Xecrets.Sdk.Abstractions.IXfApi') ready to use.
+## XfApiFactory(string, bool, string, IScheduler, IScheduler) Constructor
 
-### Remarks
-Should normally not be used when using Axantum ready built command line tool binaries, as no license is  
-provided. Another option to provide the license is to place it in a text file next to the executable.
-
-<a name='Xecrets.Sdk.XfApiFactory.Create(string,bool,string,System.Reactive.Concurrency.IScheduler,System.Reactive.Concurrency.IScheduler)'></a>
-
-## XfApiFactory.Create(string, bool, string, IScheduler, IScheduler) Method
-
-Create an [IXfApi](Xecrets.Sdk.Abstractions.md#Xecrets.Sdk.Abstractions.IXfApi 'Xecrets.Sdk.Abstractions.IXfApi') instance with all parameters explicitly defined.
+Create an [IXfApi](Xecrets.Sdk.Abstractions.md#Xecrets.Sdk.Abstractions.IXfApi 'Xecrets.Sdk.Abstractions.IXfApi') instance.
 
 ```csharp
-public static Xecrets.Sdk.Abstractions.IXfApi Create(string license, bool debugCli, string crashLogFullName, System.Reactive.Concurrency.IScheduler taskpoolScheduler, System.Reactive.Concurrency.IScheduler mainthreadScheduler);
+public XfApiFactory(string license, bool debugCli, string crashLogFullName, System.Reactive.Concurrency.IScheduler taskpoolScheduler, System.Reactive.Concurrency.IScheduler mainthreadScheduler);
 ```
 #### Parameters
 
-<a name='Xecrets.Sdk.XfApiFactory.Create(string,bool,string,System.Reactive.Concurrency.IScheduler,System.Reactive.Concurrency.IScheduler).license'></a>
+<a name='Xecrets.Sdk.XfApiFactory.XfApiFactory(string,bool,string,System.Reactive.Concurrency.IScheduler,System.Reactive.Concurrency.IScheduler).license'></a>
 
 `license` [System.String](https://docs.microsoft.com/en-us/dotnet/api/System.String 'System.String')
 
-A Xecrets license string to provide for a ready built version of  
-            XecretsCli.
+A Xecrets license string to provide for a ready built version of XecretsCli.
 
-<a name='Xecrets.Sdk.XfApiFactory.Create(string,bool,string,System.Reactive.Concurrency.IScheduler,System.Reactive.Concurrency.IScheduler).debugCli'></a>
+<a name='Xecrets.Sdk.XfApiFactory.XfApiFactory(string,bool,string,System.Reactive.Concurrency.IScheduler,System.Reactive.Concurrency.IScheduler).debugCli'></a>
 
 `debugCli` [System.Boolean](https://docs.microsoft.com/en-us/dotnet/api/System.Boolean 'System.Boolean')
 
 Set to [true](https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/bool 'https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/bool') to cause the command line to stop on a breakpoint and  
             enable attaching a debugger. (Windows only)
 
-<a name='Xecrets.Sdk.XfApiFactory.Create(string,bool,string,System.Reactive.Concurrency.IScheduler,System.Reactive.Concurrency.IScheduler).crashLogFullName'></a>
+<a name='Xecrets.Sdk.XfApiFactory.XfApiFactory(string,bool,string,System.Reactive.Concurrency.IScheduler,System.Reactive.Concurrency.IScheduler).crashLogFullName'></a>
 
 `crashLogFullName` [System.String](https://docs.microsoft.com/en-us/dotnet/api/System.String 'System.String')
 
 The full path where the command line can write a crash log on non-zero return  
             status.
 
-<a name='Xecrets.Sdk.XfApiFactory.Create(string,bool,string,System.Reactive.Concurrency.IScheduler,System.Reactive.Concurrency.IScheduler).taskpoolScheduler'></a>
+<a name='Xecrets.Sdk.XfApiFactory.XfApiFactory(string,bool,string,System.Reactive.Concurrency.IScheduler,System.Reactive.Concurrency.IScheduler).taskpoolScheduler'></a>
 
 `taskpoolScheduler` [System.Reactive.Concurrency.IScheduler](https://docs.microsoft.com/en-us/dotnet/api/System.Reactive.Concurrency.IScheduler 'System.Reactive.Concurrency.IScheduler')
 
 An [System.Reactive.Concurrency.IScheduler](https://docs.microsoft.com/en-us/dotnet/api/System.Reactive.Concurrency.IScheduler 'System.Reactive.Concurrency.IScheduler') instance to schedule work on the  
             taskpool.
 
-<a name='Xecrets.Sdk.XfApiFactory.Create(string,bool,string,System.Reactive.Concurrency.IScheduler,System.Reactive.Concurrency.IScheduler).mainthreadScheduler'></a>
+<a name='Xecrets.Sdk.XfApiFactory.XfApiFactory(string,bool,string,System.Reactive.Concurrency.IScheduler,System.Reactive.Concurrency.IScheduler).mainthreadScheduler'></a>
 
 `mainthreadScheduler` [System.Reactive.Concurrency.IScheduler](https://docs.microsoft.com/en-us/dotnet/api/System.Reactive.Concurrency.IScheduler 'System.Reactive.Concurrency.IScheduler')
 
 An [System.Reactive.Concurrency.IScheduler](https://docs.microsoft.com/en-us/dotnet/api/System.Reactive.Concurrency.IScheduler 'System.Reactive.Concurrency.IScheduler') instance to schedule work on the main (GUI)  
             thread.
+### Methods
+
+<a name='Xecrets.Sdk.XfApiFactory.Create(System.Threading.CancellationToken)'></a>
+
+## XfApiFactory.Create(CancellationToken) Method
+
+Create an [IXfApi](Xecrets.Sdk.Abstractions.md#Xecrets.Sdk.Abstractions.IXfApi 'Xecrets.Sdk.Abstractions.IXfApi') instance.
+
+```csharp
+public Xecrets.Sdk.Abstractions.IXfApi Create(System.Threading.CancellationToken ct);
+```
+#### Parameters
+
+<a name='Xecrets.Sdk.XfApiFactory.Create(System.Threading.CancellationToken).ct'></a>
+
+`ct` [System.Threading.CancellationToken](https://docs.microsoft.com/en-us/dotnet/api/System.Threading.CancellationToken 'System.Threading.CancellationToken')
+
+A cancellation token to cancel any long running operation.
+
+Implements [Create(CancellationToken)](Xecrets.Sdk.Abstractions.md#Xecrets.Sdk.Abstractions.IXfApiFactory.Create(System.Threading.CancellationToken) 'Xecrets.Sdk.Abstractions.IXfApiFactory.Create(System.Threading.CancellationToken)')
+
+#### Returns
+[IXfApi](Xecrets.Sdk.Abstractions.md#Xecrets.Sdk.Abstractions.IXfApi 'Xecrets.Sdk.Abstractions.IXfApi')
+
+<a name='Xecrets.Sdk.XfApiFactory.Safe()'></a>
+
+## XfApiFactory.Safe() Method
+
+Create an [IXfApi](Xecrets.Sdk.Abstractions.md#Xecrets.Sdk.Abstractions.IXfApi 'Xecrets.Sdk.Abstractions.IXfApi') instance with safe defaults.
+
+```csharp
+public static Xecrets.Sdk.Abstractions.IXfApi Safe();
+```
 
 #### Returns
 [IXfApi](Xecrets.Sdk.Abstractions.md#Xecrets.Sdk.Abstractions.IXfApi 'Xecrets.Sdk.Abstractions.IXfApi')  
-An instance of [IXfApi](Xecrets.Sdk.Abstractions.md#Xecrets.Sdk.Abstractions.IXfApi 'Xecrets.Sdk.Abstractions.IXfApi') ready to use.
+An instance of [IXfApi](Xecrets.Sdk.Abstractions.md#Xecrets.Sdk.Abstractions.IXfApi 'Xecrets.Sdk.Abstractions.IXfApi') ready to use.
+
+### Remarks
+Should normally not be used when using Axantum ready built command line tool binaries, as no license is  
+provided. Another option to provide the license is to place it in a text file next to the executable.

sdk-docs/Xecrets.Sdk.md

@@ -4,7 +4,7 @@
 
 | Classes | |
 | :--- | :--- |
-| [XfApiFactory](Xecrets.Sdk.XfApiFactory.md 'Xecrets.Sdk.XfApiFactory') | Static factory methods to create an [IXfApi](Xecrets.Sdk.Abstractions.md#Xecrets.Sdk.Abstractions.IXfApi 'Xecrets.Sdk.Abstractions.IXfApi') implementation. |
+| [XfApiFactory](Xecrets.Sdk.XfApiFactory.md 'Xecrets.Sdk.XfApiFactory') | Create an [IXfApi](Xecrets.Sdk.Abstractions.md#Xecrets.Sdk.Abstractions.IXfApi 'Xecrets.Sdk.Abstractions.IXfApi') instance. |
 | [XfException](Xecrets.Sdk.XfException.md 'Xecrets.Sdk.XfException') | The exception type thrown when something goes wrong calling the command line tool. In addition to the base class<br/>[System.Exception](https://docs.microsoft.com/en-us/dotnet/api/System.Exception 'System.Exception') there is an [ExitCode](Xecrets.Sdk.XfException.md#Xecrets.Sdk.XfException.ExitCode 'Xecrets.Sdk.XfException.ExitCode') property containing the actual exit code from the<br/>tool. Exit codes are [System.Int32](https://docs.microsoft.com/en-us/dotnet/api/System.Int32 'System.Int32') but they are mapped to enum [Xecrets.Cli.Public.XfStatusCode](https://docs.microsoft.com/en-us/dotnet/api/Xecrets.Cli.Public.XfStatusCode 'Xecrets.Cli.Public.XfStatusCode') here. To ensure<br/>that the mapping is correct, call [IsSdkCompatibleWith(Version)](Xecrets.Sdk.Abstractions.md#Xecrets.Sdk.Abstractions.IXfApi.IsSdkCompatibleWith(System.Version) 'Xecrets.Sdk.Abstractions.IXfApi.IsSdkCompatibleWith(System.Version)') ./> |
 | [XfExtensions](Xecrets.Sdk.XfExtensions.md 'Xecrets.Sdk.XfExtensions') | Useful extension methods for file names |
 | [XfSdkVersion](Xecrets.Sdk.XfSdkVersion.md 'Xecrets.Sdk.XfSdkVersion') | Helper to determine if the current SDK version is compatible with a given command line tool API version. |

src/Xecrets.Cli/CancelSignal.cs

@@ -0,0 +1,78 @@
+#region Copyright and GPL License
+
+/*
+ * Xecrets Cli - Copyright © 2022-2024, Svante Seleborg, All Rights Reserved.
+ *
+ * This code file is part of Xecrets Cli, parts of which in turn are derived from AxCrypt as licensed under GPL v3 or later.
+ * 
+ * However, this code is not derived from AxCrypt and is separately copyrighted and only licensed as follows unless
+ * explicitly licensed otherwise. If you use any part of this code in your software, please see https://www.gnu.org/licenses/
+ * for details of what this means for you.
+ *
+ * Xecrets Cli is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+ *
+ * Xecrets Cli is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
+ * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along with Xecrets Cli.  If not, see <https://www.gnu.org/licenses/>.
+ *
+ * The source repository can be found at https://github.com/ please go there for more information, suggestions and
+ * contributions. You may also visit https://www.axantum.com for more information about the author.
+*/
+
+#endregion Copyright and GPL License
+
+using System.Runtime.InteropServices;
+
+namespace Xecrets.Cli;
+
+internal class CancelSignal : IDisposable
+{
+    private PosixSignalRegistration? _posixRegistration;
+
+    private CancellationTokenSource? _immediateShutdownSource = new();
+
+    public CancellationToken ImmediateToken => _immediateShutdownSource?.Token ??
+        throw new ObjectDisposedException(nameof(ImmediateToken));
+
+    public CancelSignal()
+    {
+        _posixRegistration = PosixSignalRegistration.Create(PosixSignal.SIGINT, (h) =>
+        {
+            h.Cancel = true;
+            _immediateShutdownSource.Cancel();
+        });
+    }
+
+    protected virtual void Dispose(bool disposing)
+    {
+        if (!disposing)
+        {
+            return;
+        }
+
+        if (_immediateShutdownSource != null)
+        {
+            _immediateShutdownSource.Dispose();
+            _immediateShutdownSource = null;
+        }
+
+        if (_posixRegistration != null)
+        {
+            _posixRegistration.Dispose();
+            _posixRegistration = null;
+        }
+    }
+
+    public void Dispose()
+    {
+        Dispose(true);
+        GC.SuppressFinalize(this);
+    }
+
+    ~CancelSignal()
+    {
+        Dispose(false);
+    }
+}

src/Xecrets.Cli/Executor.cs

@@ -35,25 +35,37 @@ internal class Executor(Parameters parameters) : IDisposable
 {
     public async Task<Status> RunAsync()
     {
-        Status status = await RunAsync(new DryRunFactory(parameters));
-        if ((parameters.Parser.IsQuiet || parameters.Parser.Internal) && status.IsSuccess)
+        try
         {
-            New<Splash>().Clear();
-        }
+            Status status = await RunAsync(new DryRunFactory(parameters));
+            if ((parameters.Parser.IsQuiet || parameters.Parser.Internal) && status.IsSuccess)
+            {
+                New<Splash>().Clear();
+            }
 
-        if (!status.IsSuccess)
-        {
-            return status;
-        }
+            if (!status.IsSuccess)
+            {
+                return status;
+            }
 
-        if (parameters.Parser.IsDryRunOnly)
-        {
-            return new Status("A successful dry run was executed, no files were changed.");
-        }
+            if (parameters.Parser.IsDryRunOnly)
+            {
+                return new Status("A successful dry run was executed, no files were changed.");
+            }
 
-        ResetParametersForRealRun();
+            ResetParametersForRealRun();
 
-        return await RunAsync(new RealRunFactory(parameters));
+            return await RunAsync(new RealRunFactory(parameters));
+        }
+        catch (OperationCanceledException oce)
+        {
+            return new Status(XfStatusCode.Canceled, oce.Message)
+            {
+                Id = parameters.TotalsTracker.Id,
+                Arg1 = parameters.Arg1,
+                Arg2 = parameters.Arg2,
+            };
+        }
     }
 
     private void ResetParametersForRealRun()

src/Xecrets.Cli/Log/TotalsTracker.cs

@@ -26,6 +26,8 @@
 using Xecrets.Cli.Public;
 using Xecrets.Cli.Run;
 
+using static AxCrypt.Abstractions.TypeResolve;
+
 namespace Xecrets.Cli.Log;
 
 internal class TotalsTracker
@@ -48,8 +50,11 @@ internal class TotalsTracker
 
     public string Id { get; set; } = string.Empty;
 
+    private readonly CancelSignal _cancelSignal;
+
     public TotalsTracker()
     {
+        _cancelSignal = New<CancelSignal>();
         Logger = GetCurrentLogger();
     }
 
@@ -84,20 +89,32 @@ public void AddWorkItem(long count)
     {
         AddWork(count);
         ItemsTotal += 1;
+        AssertNoCancel();
     }
 
     public void AddWork(long count)
     {
         TotalWork += count;
+        AssertNoCancel();
     }
 
     public void DoWork(long count)
     {
         TotalDone += count;
+        AssertNoCancel();
     }
 
     public void DoItems(int items)
     {
         ItemsDone += items;
+        AssertNoCancel();
+    }
+
+    private void AssertNoCancel()
+    {
+        if (_cancelSignal.ImmediateToken.IsCancellationRequested)
+        {
+            throw new OperationCanceledException("Operation immediately canceled.");
+        }
     }
 }