/*
* Copyright (c) 2022 Vaughn Nugent
*
* Library: VNLib
* Package: VNLib.Plugins.PluginBase
* File: PluginBase.cs
*
* PluginBase.cs is part of VNLib.Plugins.PluginBase which is part of the larger
* VNLib collection of libraries and utilities.
*
* VNLib.Plugins.PluginBase 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 2 of the License,
* or (at your option) any later version.
*
* VNLib.Plugins.PluginBase 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 VNLib.Plugins.PluginBase. If not, see http://www.gnu.org/licenses/.
*/
using System;
using System.IO;
using System.Linq;
using System.Text.Json;
using System.Threading;
using System.Threading.Tasks;
using System.Collections.Generic;
using Serilog;
using VNLib.Utils.Logging;
using VNLib.Utils.Extensions;
using VNLib.Plugins.Attributes;
namespace VNLib.Plugins
{
///
/// Provides a concrete base class for instances using the Serilog logging provider.
/// Accepts the standard plugin configuration constructors
///
public abstract class PluginBase : MarshalByRefObject, IPlugin
{
/*
* CTS exists for the life of the plugin, its resources are never disposed
* such not to disturb late running tasks that depend on the cts's state
*/
private readonly CancellationTokenSource Cts = new();
private readonly LinkedList DeferredTasks = new();
///
/// A cancellation token that is cancelled when the plugin has been unloaded
///
public CancellationToken UnloadToken => Cts.Token;
///
/// The property name of the host/global configuration element in the plugin
/// runtime supplied configuration object.
///
protected virtual string GlobalConfigDomPropertyName => "host";
///
/// A list of all currently prepared endpoints.
/// Endpoints must be added to this list before is called
/// by the host app
///
public ICollection Endpoints { get; } = new List();
///
/// The logging instance
///
public ILogProvider Log { get; private set; }
///
/// If passed by the host application, the configuration file of the host application and plugin
///
protected JsonDocument Configuration { get; private set; }
///
/// The configuration data from the host application
///
public JsonElement HostConfig { get; private set; }
///
/// The configuration data from the plugin's config file passed by the host application
///
public JsonElement PluginConfig { get; private set; }
///
///
///
public abstract string PluginName { get; }
///
/// The file/console log template
///
protected virtual string LogTemplate => $"{{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz}} [{{Level:u3}}] {PluginName}: {{Message:lj}}{{NewLine}}{{Exception}}";
///
/// The host application may invoke this method when the assembly is loaded and this plugin is constructed to pass
/// a configuration object to the instance. This method populates the configuration objects if applicable.
///
[ConfigurationInitalizer]
public virtual void InitConfig(JsonDocument config)
{
_ = config ?? throw new ArgumentNullException(nameof(config));
//Store config ref to dispose properly
Configuration = config;
//Load congfiguration elements
HostConfig = config.RootElement.GetProperty(GlobalConfigDomPropertyName);
//Plugin config propery name is the name of the current type
PluginConfig = config.RootElement.GetProperty(this.GetType().Name);
}
///
/// Responsible for initalizing the log provider. The host should invoke this method
/// directly after the configuration is initialized
///
///
[LogInitializer]
public virtual void InitLog(string[] cmdArgs)
{
//Get the procce's command ling args to check for logging verbosity
List args = new(cmdArgs);
//Open new logger config
LoggerConfiguration logConfig = new();
//Check for verbose
if (args.Contains("-v"))
{
logConfig.MinimumLevel.Verbose();
}
//Check for debug mode
else if (args.Contains("-d"))
{
logConfig.MinimumLevel.Debug();
}
//Default to information
else
{
logConfig.MinimumLevel.Information();
}
//Init console log
InitConsoleLog(cmdArgs, logConfig);
//Init file log
InitFileLog(logConfig);
//Open logger
Log = new VLogProvider(logConfig);
}
private void InitConsoleLog(string[] args, LoggerConfiguration logConfig)
{
//If silent arg is not specified, open log to console
if (!(args.Contains("--silent") || args.Contains("-s")))
{
logConfig.WriteTo.Console(outputTemplate: LogTemplate);
}
}
private void InitFileLog(LoggerConfiguration logConfig)
{
string filePath = null;
string template = null;
TimeSpan flushInterval = TimeSpan.FromSeconds(10);
int retainedLogs = 31;
//Default to 500mb log file size
int fileSizeLimit = 500 * 1000 * 1024;
RollingInterval interval = RollingInterval.Infinite;
//try to get the host's app_log config object
if (HostConfig.TryGetProperty("app_log", out JsonElement logEl))
{
IReadOnlyDictionary conf = logEl.EnumerateObject().ToDictionary(static s => s.Name, static s => s.Value);
filePath = conf.GetPropString("path");
template = conf.GetPropString("template");
if (conf.TryGetValue("flush_sec", out JsonElement flushEl))
{
flushInterval = flushEl.GetTimeSpan(TimeParseType.Seconds);
}
if (conf.TryGetValue("retained_files", out JsonElement retainedEl))
{
retainedLogs = retainedEl.GetInt32();
}
if (conf.TryGetValue("file_size_limit", out JsonElement sizeEl))
{
fileSizeLimit = sizeEl.GetInt32();
}
if (conf.TryGetValue("interval", out JsonElement intervalEl))
{
interval = Enum.Parse(intervalEl.GetString()!, true);
}
}
//Default if not set
filePath ??= Path.Combine(Environment.CurrentDirectory, $"{PluginName}.txt");
template ??= LogTemplate;
//Configure the log file writer
logConfig.WriteTo.File(filePath,
buffered: true,
retainedFileCountLimit: retainedLogs,
fileSizeLimitBytes: fileSizeLimit,
rollingInterval: interval,
outputTemplate: template,
flushToDiskInterval: flushInterval);
}
///
/// When overriden handles a console command
///
///
[ConsoleEventHandler]
public void HandleCommand(string cmd)
{
try
{
ProcessHostCommand(cmd);
}
catch(Exception ex)
{
Log.Error(ex);
}
}
///
/// Invoked when the host process has a command message to send
///
/// The command message
protected abstract void ProcessHostCommand(string cmd);
IEnumerable IPlugin.GetEndpoints()
{
OnGetEndpoints();
return Endpoints;
}
void IPlugin.Load()
{
//Setup empty log if not specified
Log ??= new VLogProvider(new());
//Default logger before loading
Configuration ??= JsonDocument.Parse("{}");
try
{
//Try to load the plugin and cleanup since the plugin failed to load
OnLoad();
}
catch
{
//Cancel the token
Cts.Cancel();
//Cleanup
CleanupPlugin();
throw;
}
}
void IPlugin.Unload()
{
try
{
//Cancel the token
Cts.Cancel();
//Call unload impl
OnUnLoad();
//Wait for bg tasks
WaitForTasks();
}
finally
{
CleanupPlugin();
}
}
private void CleanupPlugin()
{
//Dispose the config document
Configuration?.Dispose();
//dispose the log
(Log as IDisposable)?.Dispose();
//Clear endpoints list
Endpoints.Clear();
//empty deffered array
DeferredTasks.Clear();
}
private void WaitForTasks()
{
const int WARNING_INTERVAL = 1500;
void OnTimerElapsed(object state)
{
//Write time errors to log
Log.Warn("One or more deferred background tasks are taking a long time to complete");
}
if(DeferredTasks.Count > 0)
{
//Startup timer to warn if tasks are taking a long time to complete
using Timer t = new(OnTimerElapsed, this, WARNING_INTERVAL, WARNING_INTERVAL);
Task[] tasks;
lock (DeferredTasks)
{
//Copy tasks to array
tasks = DeferredTasks.ToArray();
}
//Wait for all tasks to complete for a maxium of 10 seconds
Task.WaitAll(tasks, TimeSpan.FromSeconds(10));
}
}
///
/// Adds a task to the observation list
///
/// The task to observe
public void ObserveTask(Task task)
{
lock (DeferredTasks)
{
DeferredTasks.AddFirst(task);
}
}
///
/// Removes a task from the task observation list
///
/// The task to remove
public void RemoveObservedTask(Task task)
{
lock (DeferredTasks)
{
DeferredTasks.Remove(task);
}
}
///
///
/// Invoked when the host loads the plugin instance
///
///
/// All endpoints must be routed before this method returns
///
///
protected abstract void OnLoad();
///
/// Invoked when all endpoints have been removed from service. All managed and unmanged resources should be released.
///
protected abstract void OnUnLoad();
///
/// Invoked before called by the host app to get all endpoints
/// for the current plugin
///
protected virtual void OnGetEndpoints() { }
///
/// Adds the specified endpoint to be routed when loading is complete
///
/// The to present to the application when loaded
public void Route(IEndpoint endpoint) => Endpoints.Add(endpoint);
}
}