Price Provider Library Plugin

[Crypta-Eve]

SOURCE @recursivetree: https://gist.github.com/recursivetree/0add09325b290f227f87d497ec6376dc

Situation

Many plugins for the SeAT ecosystem rely on prices to function properly. The following list contains the most
notable ones:

• seat-srp
• seat-buyback
• seat-billing
• seat-alliance-industry
• seat-transport
• seat-fitting

Currently, all these plugin have their own way of getting prices. Many depend on the now shut-down evepraisal
service, and some use the data provided by the SeAT core. The most important takeaway here is that all of these
plugins work and behave differently.

Why is this bad?

• A recent example: After the evepraisal shutdown, some plugins stopped working
• Users are more likely to be confused because each plugin works differently
• A lot of code is duplicated across all these plugins, increasing the maintenance burden
• Some users might want to use a different type of price, e.g. buy instead of sell prices. There is also the
  potential for exotic price providers that value items by e.g. the time it takes to build them (this has been
  requested and implemented in seat-alliance-industry).

Proposal

Implement a library plugin providing accurate price information to plugins. The implementation should be in a way
that allows users to select a price source ('price provider') individually for each plugin/use case. This is
basically what already exists and works well in seat-alliance-industry and seat-transport: In their settings there is a
list of price providers the users can select for use in their plugins. Possible price providers are:

• evepraisal and clones
• https://janice.e-351.com/
• https://market.fuzzwork.co.uk/
• (sometimes inaccurate) ESI Prices currently used in SeAT
• Calculators for build cost
• Simply a table providing the value
• I'm sure there are endless possibilities

That being said, not all of them need to be implemented.

Implementation

This will get technical!

Requirements

• provide prices
• easy to integrate into existing plugins
• extensible, available price providers shouldn't be limited to the plugin, other plugins should be able to register
  more price providers.
• Price providers will need to have configuration associated with them. For example, this can be the market region,
  sell or buy prices or a value modifier. My experience from seat-transport and seat-alliance-industry tells me that
  it's not enough to have one set of options that works for all price providers, they will need to be configurable
  on a per price provider base.
• It should be possible to use multiple instances of the same price provider with different configurations at the
  same time
• You should be able to request prices for multiple items at once to reduce API calls for implementations that use APIs.

Architecture Suggestion

To achieve the goal of having multiple instances of the same price provider with different configurations at the
same time, I suggest introducing two concepts: A price provider instance and a price provider implementation.

The price provider instance is a normal database model containing a reference to a price provider implementation and
the configuration it needs. There will be a page to create price provider instances: Users can select an
implementation and configure its settings. Once the instance is created, in the plugin settings users can select a
price provider instance to use. When plugins need price data, they can load the model representing the price
provider instance and ask for prices:

$price_provider_instance = PriceProviderInstances::find($my_price_provider_instance_id_selected_in_settings);
$prices = $price_provider_instance->getPrices($my_item_list);

A price provider implementation is the code that actually loads price data. I imagine it as a class that implements an
interface containing a single method: getPrices($items, $configuration). There will be a way to register price
provider implementations, so they appear in the list of price provider implementations when creating a price
provider instance. Other plugins can extend the available price providers by registering their price provider
implementations too. I suggest doing configuration creation the same way it is handled in eveseat/notifications for
discord mentions.

Open Questions

• Always return the price for one item or take in an amount and return item price times amount?
  • I tend to take in an amount, as it is not much more work to implement it, but potentially makes plugin
    integration simpler.
• Price provider registry: config or service container based?
  • SeAT core mostly uses config
• Dow we want caching? If so, do it as plugin or leave it to the price provider implementations?
• Should we contribute this to the seat core instead of making it as a plugin?
• How do we want to move on? I can contribute the initial code required for the library plugin, but I need support
  from the maintainers for plugin integration.
• seat-billing needs prices as a database model. Unless other plugins need that too I'll find a way to solve it
  without having this in the library.

[Crypta-Eve]

Ok, I am moving this here so we can have a living history of discussion.

I agree that we should have a centralised registry of these providers. I personally am open to this being a plugin, but am thinking that it would probably also belong in core. Being in core, there would be the centralised config (I am not across service vs config and the impacts) and a provider that delivers pricing based upon the seat prices model.

RT Questions

• Always return the price for one item or take in an amount and return item price times amount?

  • Happy to take an amount, and yes will make easier integration within plugins

• Price provider registry: config or service container based?

  • I am not familiar with service container and am used to config, but open to either as I am not aware of the tradeoffs.

• Dow we want caching? If so, do it as plugin or leave it to the price provider implementations?

  • I think yes, but should be the responsibility of the price provider as this may vary significantly between providers.

• Should we contribute this to the seat core instead of making it as a plugin?

  • My vote would be integration into core. Perhaps in the service package (looking for guidance from @warlof )

• How do we want to move on? I can contribute the initial code required for the library plugin, but I need support
  from the maintainers for plugin integration.

  • I am happy to provide the implementation for seat-srp and seat-fitting initially, as well as contribute some pricing backends.

  Crypta Questions

• I think that other than the core prices model provider, the remainder of providers should live in an external plugin. I am in a couple of conflicting minds here though. In my order of preference; each backend has an individual plugin, each maintainer has a plugin with their backends, all backends reside in a central plugin that we all contribute to.

[recursivetree]

• Price provider registry: config or service container based?
  • Let's do config then
• Caching
  • Let's do it as you suggested
• Core or plugin
  • We can do core too. I don't think it really matters. Regarding where, services looks fitting, but I see one issue: Even if most price providers reside in plugins, a basic price provider offering prices from the price data seat already has should be available in the core. This will depend on eveapi, a dependency serivces currently doesn't have.
    • We could also split it even further, the core of the system in services and the backend in eveapi
• Regarding where to place provider backends when it's in the core, we need to avoid one thing: There shouldn't be two evepraisal price providers, e.g. from seat-transport and seat-srp. Therefore, the provider backend must be separate from their parent plugin(seat-srp/seat-transport). As long as that is given, I'm fine with anything. So if you prefer one plugin per backend, let's do it.

New Questions

• Target SeAT 4 or 5? SeAT 5 is read imo, but warlof hasn't pressed the release button and we don't know when he will.

Once the questions are resolved I'll implement the core of the system.

[Crypta-Eve]

At this point I think we should target v5.. I am not sure how your plugins have fared with the loss of evepraisal, but with your update to srp I am back in business for now with v4.

I agree with the separation between provider and backend in core between services and eveapi respectively.

[recursivetree]

My considerations with targeting seat 4 was exactly to mitigate the evepraisal shutdown impact. But if you feel the current fix is enough, I agree targeting seat 5 is better.

Regarding the separation inside seat core, I found another issue: Creating price providers requires some web ui work. For that, we will need to depend on web to get the layout and auth. Services does not depend, and should not depend on web (@warlof, is this correct?). Splitting across services, eveapi and web seems a bit excessive.

What I suggest is to write it like notifications. Seat works without the notifications package and it resides in it's own package instead of web, but it is still considered part of the core. Basically write it as a plugin, but make the plugin part of core.

If we go down this route, can someone create a repository for it, so I can start implementing?

[warlof]

Indeed, services MUST live alone
You can see it as Illuminate/Contracts

It's a package of interfaces and pure business classes (ie: parsers)
Web is UI, but we might have to split it in more sub packages => breaking changes, cannot target SeAT 5

With my comment bellow, eveapi as dependency would be excluded

As of repository, you'll need a name to start with and assistance of @leonjza 😊 together with it's composer registration (not sure I have enough power on packagist to sort this either)

[recursivetree]

yes, there are two ways to go: split it across services, eveapi and web, or having a prices submodule. I'm in favor of having a prices submodule, but we can also do it split.

[warlof]

I agree with submodules - but contracts should be in services
This way, you can implement your own price provider (which is mostly the purpose of this, isn't it ?) without requiring all SeAT sub-packages

The same apply to third party - if you need the price provider, you don't need all SeAT sub-packages - except the services one, which will provide you the prices manager (or availables prices managers ?)

[warlof]

Just posting this as an industry grade implementation of price management
https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-extending-best-price-calculations

It's used in ERP and allow basically any kind of price integration
Mostly - you have a thing on which you want to put a price (ie: a purchase line) and the thing for which you want the price (ie: an item, a ship, a skill, etc...)

Context will determine if you're talking about cost, charge, price or whatever

Anyway, back to SeAT

• contracts must live in services packages
• you can spawn implementation in new package, allowing plugins to require the contract and core to provide it (target low coupling)
• regarding the provided implementation, provide a factory/facade which will return requested implementation based on submitted context (see how Laravel Database, Cache or Logger is working for instance). This way, you can provide a list of available implementation using key/human readable dictionary (notification or ACL system can be a source of inspiration)

With PoC of model relationship injection, we probably even be more flexible and go further

Target ? SeAT 5, SeAT 6 if breaking changes - such a question 🤣

[recursivetree]

Ok, so what I understand out of this:

• services has an IPriceProviderBackend interface to implement price providers
• eveapi contains the price providers provided by SeAT
• web contains the UI to create price provider instances
• where do we put the model for the price provider instances?
• how do plugins get an instance and what do we use as an identifier for an instance?
  • What I would have done is to directly let plugins access the model storing the instances and add some helpers for ease of use. Plugins store an id of an instance.
  • Or would you introduce a facade for plugin that takes an id and basically wraps the model? In which package would you put that? It'd probably require a prices package, since that's an implementation. Or is services allowed to provide it's own implementation?

[recursivetree]

To me, this seems a bit needlessly complicated to get flexibility that realistically no one will ever need (extending the available price providers will always be included), even if it is the cleaner design by the laravel zen. On the other hand, I need to say that I don't fully understand the service container and especially when and how to use it yet.

This can also be made into an argument against such an implementation: This feature is primarily aimed at plugins, of which none I encountered uses the service container. To get it to be adapted, we have to keep it accessible.

[recursivetree]

If your are fine with it, I'll go down the notifications route, creating a prices module that's basically a plugin, but in seat.

One reason to do it this way is that services is a relatively hostile environment: For example, I was thinking about the API for the price provider, especially the way they receive the items they should fetch the price off. This is part of the interface, so it belongs in the 'contracts' part of the plugin. The idea is to have a PriceItem (name not final) holding a type id. For convenience, the constructor should take in an int or a InvType. Except hold, we can't reference InvType in services! Of course you could introduce an interface etc, but at some point it is just absurd. It's these little things.

The prices package will still be pretty much the core functionality required to get the system to work, without price provider implementations.

I agree that reducing coupling is important, but I don't think it is worth it here. I bet that nobody ever will write an alternative implementation for parts of seat, or if so, we can take a look at it when it happens.

[warlof]

services => IPriceProviderBackend + price facade allowing you to return available price providers and implementation of requested provider
new package => one price provider

what do you want to do with eveapi and web ?
regarding identifier, config file and binding will tell you

taking back Laravel point of view with cache sample :
https://github.com/laravel/framework/tree/10.x/src/Illuminate/Cache -> implementation of cache
https://github.com/laravel/framework/tree/10.x/src/Illuminate/Contracts/Cache -> cache contracts
https://github.com/laravel/laravel/blob/10.x/config/cache.php config which provide you available prices providers together with their implementation (https://github.com/laravel/laravel/blob/10.x/config/cache.php#L34-L96) - and the default one (https://github.com/laravel/laravel/blob/10.x/config/cache.php#L18)

ence for usage, you can do on of :

PriceProvider::get(IPriceable) // return price for an IPriceable using default engine
PriceProvider::engine('seat-srp')->get(IPriceable) // return price for an IPriceable using seat-srp engine

where IPriceable is another contract which must be implemented by stuff for which price manager have to return a price (to be honest, I think it's required as we might need to submit something else than a InvType)

[recursivetree]

Thanks, providing a code example helps a lot with understanding your idea.

However, I think you have a slight misunderstanding of how it is supposed to work (although it doesn't matter a lot for my questions). I'd recommend to reread the original, first proposal. A price provider backend/engine will need configuration(from my experience with seat-treelib). This configuration must be made over the UI, thus touching web.

eveapi was mentioned in this context just because it has price data we could use. It doesn't matter for the implementation of the core where we place that.

I think I'll just try to implement a POC and see how it goes. Sometimes learning by doing is best.

[recursivetree]

Update: Since CCP asked to shut down/reduce the amount of alternative evepraisal hosts, we wanted to accelerate the development a bit. Therefore we decided to place it in a plugin instead of the core to allow for faster development. The plugin is hosted here: https://github.com/recursivetree/seat-prices-core

[recursivetree]

I switch one of my plugins to the new system on this branch: https://github.com/recursivetree/seat-transport/tree/seat-prices-core-integration, if anyone is interested.

[warlof]

What about architecture and modeling ?

[recursivetree]

Sorry, I didn't really publish this in public. I talked with crypta that given the drama about evepraisal (I think you aren't on the eve partner discord, but they basically asked us to shut down or fix all evepraisal clones that popped up) that we need the plugin sooner than expected. Since developing for core is always slower than a plugin, we decided to switch to a plugin.

Architecture was already more or less fixed besides whether we have an API directly on the model representing a price provider instance or not. Modeling is trivial, we just have one table and the data to be stored is kind of obvious.

With the long term goal of bringing this into core, we have to do breaking changes anyways to migrate namespaces at some point. This could also be used as an opportunity to introduce a new API layer.

[warlof]

Don't worry - I just asked about modeling so I could figure how it should work without reading code 😅

Also see a part of the Eve praisal drama from Crypta notification. But that's not what inquire me here 🙂

[recursivetree]

While it doesn't cover everything about the implementation, you can read the developer documentation for integrating the plugin into plugins: https://github.com/recursivetree/seat-prices-core/blob/master/developer_documentation.md. It explains most of it.