[enh] simple API plugin framework

[jpcsupplies]

Summary: A simplistic system to allow other plugin makers to support money transactions within Frontier Economy.

Synopsis:
3rd party plugins append transaction requests to a global file, economy periodically checks and processes these requests. Economy creates a "flag" file to indicate to other plugins it is running to prevent transactions being queued if it is not present. 3rd party plugins supporting optional economic features check for this file before attempting to issue requests. Code samples for how to interact with this file can be included in the economy manual for mod makers to easily add such support.

Security concerns:
1: Players may create plugins with the express purpose of swindling money. However the command file will only be checked server side, which limits such exploits to plugins the server admin deliberately installed, instead of client side "ghost" plugins, which will be ignored as they are not interacting server side.
2: It may be possible to over draw accounts, or for a transaction to fail. It should never overdraw on the economy side, so 3rd party plugins need a way to detect a transaction has failed.

Basic function:
On launch economy creates a blank file in the global storage area named "Economy.online"
When shutting down economy deletes this file. It serves no other purpose but to indicate to other plugins that economy is currently running on a server.

Communication is essentially one way - plugins can issue commands to economy but economy will not talk back. However such transactions could be logged to a global file allowing 3rd party plugins to check if its request was processed. Economy could also generate a "failed transactions" file in the case the requested player either doesn't exist or lacks enough funds. Economy could also potentially create a economy.processing file, but a simple try catch retry when appending commands to the file should be adequate.

While running economy will periodically check for a global file named for example "economy.txt" this file must contain four things per transaction:

1: payer ID (Source of funds. Either steam name and/or steam ID, or a keyword indicating generate new or NPC)
2: payee ID (Target of funds. Either steam name and/or steam ID, or a keyword indicating destroy funds or NPC)
3: Transaction amount. (OR it could also be an item/qty to allow more flexibility for plugins)
4: Transaction reason - ideally including at least the requesting mod name

The file can contain more than one transaction.

Once processed the transactions (or entire file) will be deleted to prevent double processing.

3rd party mod restrictions:
mods talking to economy should only ever APPEND to the file
mods should only READ the transaction log or failed transactions file

Concerns:
failed transaction file may become very large, it may be necessary to require 3rd party mods delete any failed transactions they have already processed to reduce potential performance impact.
If more than one 3rd party plugin exists simply deleting the failed transaction file will cause problems, it may also be necessary for 3rd party plugins to generate a transaction ID so they only delete their own failed transactions.

Ideally a simple communication framework negating the need for a transaction file entirely is preferable - although the online flag file can probably still be used.
In this case a transaction would be along the lines of:
3rd party plugin sends Payer, Payee, amount, reason, requesting mod, optional transaction ID.
Economy responds to requesting mod with Payer, Payee, amount, reason, approved/failed, optional transaction ID

Example 3rd party plugins:
Stargate mod - charge a fee per trip
Frontier Territory mod - charge an entry tax when crossing into another factions territory.
Gateway lobby mod - charge a fee to travel to another sector
Mail order ships mod - charge a fee to spawn in a prefab (eg something like the midspace admin helper mod /addprefab # command)
NPC courier mod - charge a fee to transport goods etc
Jobs Mod - pay a player a wage for performing tasks
Rewards/Gifts/Prizes mods - pay a player a prize in money or goods (eg tier 10 weapon tokens etc)

[jpcsupplies]

Work arounds - if we require a mod name field, use that for the failed transactions filename, the originating mod is then free to safely examine/process/delete this file without conflicting with another mod.

Economy API Datafiles:
Flag file to let other mods detect it is running. Created on Launch, Deleted on Shutdown.
Economy.Online

• Contains no useful data

EconomyAPI.log

• Timestamp, Plugin (Originating mod) Tried to transfer XX funds between payer / payee for Reason

Economy.txt
Economy can read/delete file. Payer can be player, Generate or NPC, Payee can be player, Destroy or NPC.

• Payer, Payee, Amount, Originating Mod, Reason

Originating_Mod.failed
Economy is only allowed to Append to file.

• Payer, Payee, Amount, Reason for Failure, Original Reason

Economy API Supporting Mods:
Economy.txt

• Append access only.

Originating_Mod.failed

• Mod has read/write access, and delete access.
  Used to indicate failed payment attempts. Filename is generated from the "Originating Mod" field.

Notes:

• "Payer" Either a player name/steam ID or a reserved code for the person whom we are deducting from.
• "Payee" Either a player name/steam ID or a reserved code for the person whom we are giving to.

Reserved codes:

• "Generate" indicates new money or items should be created to fill this payment instead of deducting from NPC. (Mission rewards, etc)
• "Destroy" indicates this money or item should be removed from the game instead of given to NPC. (Junk, or other sundry reasons)
• "NPC" indicates the money or items should be added or removed from the NPC to fill this transaction.

[midspace]

This was added back in January. Don't know how well it works.
Inter-Mod communication. In IMyUtilities, you'll find new methods for registering and sending events, almost identical to the network communication mods have now. Instead of <short, byte[]>, you get <long, object> so you can pass any data at all between mods on the same client.
https://forum.keenswh.com/threads/modapi-changes-jan-26.7392280/

[jpcsupplies]

Ah ok, so skip the middle man and talk directly to each other in a single variable instead of using placeholder files -
so mods would need to accept communication indicating if the transaction succeeded or failed, and economy would have to accept communication requesting payments or transfers to be made and reply if it worked or failed..?