From 2c94684f9f4f1570c70aa8a087352c78df999031 Mon Sep 17 00:00:00 2001
From: Jon Evans <jon@craftyjon.com>
Date: Sat, 28 Dec 2024 16:20:49 -0500
Subject: [PATCH] API: Add a preferred plugin settings path

Fixes https://gitlab.com/kicad/code/kicad/-/issues/9054
---
 api/proto/common/commands/base_commands.proto | 17 ++++++++
 common/api/api_handler_common.cpp             | 40 +++++++++++++++++++
 common/api/api_plugin.cpp                     | 13 ++++--
 include/api/api_handler_common.h              |  3 ++
 include/api/api_plugin.h                      |  2 +
 5 files changed, 71 insertions(+), 4 deletions(-)

diff --git a/api/proto/common/commands/base_commands.proto b/api/proto/common/commands/base_commands.proto
index ef5976842c..e0fd5880c6 100644
--- a/api/proto/common/commands/base_commands.proto
+++ b/api/proto/common/commands/base_commands.proto
@@ -71,3 +71,20 @@ message GetTextAsShapesResponse
 {
   repeated TextWithShapes text_with_shapes = 1;
 }
+
+// Return a writeable path that a plugin can use for storing persistent data such as configuration
+// files, etc.  This path may not yet exist; actual creation of the directory for a given plugin is
+// up to the plugin itself.  Files in this path will not be modified if the plugin is uninstalled or
+// upgraded.
+//
+// Returns StringResponse
+message GetPluginSettingsPath
+{
+  // The identifier of the plugin
+  string identifier = 1;
+}
+
+message StringResponse
+{
+  string response = 1;
+}
diff --git a/common/api/api_handler_common.cpp b/common/api/api_handler_common.cpp
index 6d00b1fae1..b74f352d7c 100644
--- a/common/api/api_handler_common.cpp
+++ b/common/api/api_handler_common.cpp
@@ -26,7 +26,9 @@
 #include <eda_text.h>
 #include <geometry/shape_compound.h>
 #include <google/protobuf/empty.pb.h>
+#include <paths.h>
 #include <pgm_base.h>
+#include <api/api_plugin.h>
 #include <api/api_utils.h>
 #include <project/net_settings.h>
 #include <project/project_file.h>
@@ -49,6 +51,9 @@ API_HANDLER_COMMON::API_HANDLER_COMMON() :
             &API_HANDLER_COMMON::handleGetTextAsShapes );
     registerHandler<ExpandTextVariables, ExpandTextVariablesResponse>(
             &API_HANDLER_COMMON::handleExpandTextVariables );
+    registerHandler<GetPluginSettingsPath, StringResponse>(
+            &API_HANDLER_COMMON::handleGetPluginSettingsPath );
+
 }
 
 
@@ -223,3 +228,38 @@ HANDLER_RESULT<ExpandTextVariablesResponse> API_HANDLER_COMMON::handleExpandText
 
     return reply;
 }
+
+
+HANDLER_RESULT<StringResponse> API_HANDLER_COMMON::handleGetPluginSettingsPath(
+        const HANDLER_CONTEXT<GetPluginSettingsPath>& aCtx )
+{
+    wxString identifier = wxString::FromUTF8( aCtx.Request.identifier() );
+
+    if( identifier.IsEmpty() )
+    {
+        ApiResponseStatus e;
+        e.set_status( ApiStatusCode::AS_BAD_REQUEST );
+        e.set_error_message( "plugin identifier is missing" );
+        return tl::unexpected( e );
+    }
+
+    if( API_PLUGIN::IsValidIdentifier( identifier ) )
+    {
+        ApiResponseStatus e;
+        e.set_status( ApiStatusCode::AS_BAD_REQUEST );
+        e.set_error_message( "plugin identifier is invalid" );
+        return tl::unexpected( e );
+    }
+
+    wxFileName path( PATHS::GetUserSettingsPath(), wxEmptyString );
+    path.AppendDir( "plugins" );
+
+    // Create the base plugins path if needed, but leave the specific plugin to create its own path
+    PATHS::EnsurePathExists( path.GetPath() );
+
+    path.AppendDir( identifier );
+
+    StringResponse reply;
+    reply.set_response( path.GetPath() );
+    return reply;
+}
diff --git a/common/api/api_plugin.cpp b/common/api/api_plugin.cpp
index aeefb033c5..88bfe933b0 100644
--- a/common/api/api_plugin.cpp
+++ b/common/api/api_plugin.cpp
@@ -115,10 +115,7 @@ API_PLUGIN_CONFIG::API_PLUGIN_CONFIG( API_PLUGIN& aParent, const wxFileName& aCo
         return;
     }
 
-    // At minimum, we need a reverse-DNS style identifier with two dots and a 2+ character TLD
-    wxRegEx identifierRegex( wxS( "[\\w\\d]{2,}\\.[\\w\\d]+\\.[\\w\\d]+" ) );
-
-    if( !identifierRegex.Matches( identifier ) )
+    if( !API_PLUGIN::IsValidIdentifier( identifier ) )
     {
         wxLogTrace( traceApi, wxString::Format( "Plugin: identifier %s does not meet requirements",
                                                 identifier ) );
@@ -172,6 +169,14 @@ bool API_PLUGIN::IsOk() const
 }
 
 
+bool API_PLUGIN::IsValidIdentifier( const wxString& aIdentifier )
+{
+    // At minimum, we need a reverse-DNS style identifier with two dots and a 2+ character TLD
+    wxRegEx identifierRegex( wxS( "[\\w\\d]{2,}\\.[\\w\\d]+\\.[\\w\\d]+" ) );
+    return identifierRegex.Matches( aIdentifier );
+}
+
+
 const wxString& API_PLUGIN::Identifier() const
 {
     return m_config->identifier;
diff --git a/include/api/api_handler_common.h b/include/api/api_handler_common.h
index 20028a01cc..5aab987626 100644
--- a/include/api/api_handler_common.h
+++ b/include/api/api_handler_common.h
@@ -54,6 +54,9 @@ private:
 
     HANDLER_RESULT<commands::ExpandTextVariablesResponse> handleExpandTextVariables(
         const HANDLER_CONTEXT<commands::ExpandTextVariables>& aCtx );
+
+    HANDLER_RESULT<commands::StringResponse> handleGetPluginSettingsPath(
+        const HANDLER_CONTEXT<commands::GetPluginSettingsPath>& aCtx );
 };
 
 #endif //KICAD_API_HANDLER_COMMON_H
diff --git a/include/api/api_plugin.h b/include/api/api_plugin.h
index 54d118e4a4..06f011c0fd 100644
--- a/include/api/api_plugin.h
+++ b/include/api/api_plugin.h
@@ -110,6 +110,8 @@ public:
 
     bool IsOk() const;
 
+    static bool IsValidIdentifier( const wxString& aIdentifier );
+
     const wxString& Identifier() const;
     const wxString& Name() const;
     const wxString& Description() const;