[superceded by #1361] Add Resources path handling for those detailed in Signal K spec

[panaaj]

This branch adds path handling for routes, waypoints, notes, regions and charts for the following operations mimicking current sk-resources-fs plug-in functionality to start addressing #1351 :

• PUT
• POST
• GET
• DELETE

Additionally it defines APIs for the creation, and updating of resources removing the need for the client to understand the resource schema.
These APIs are found at the following path /signalk/v1/api/resources/set/<resource_type>

Operation:
In it's current form this PR instantiates middleware for the /signalk/v1/api/resources and /signalk/v1/api/resources/*paths.

When a path is accessed it checks if a provider has been registered for the resource type and:

• if one exists, calls the relevant interface method passing the resource type, id (and value for PUT / POST)
• if no provider is registered, calls next()
  This mode of operartion ensures backward compatibility with exisiting plugins.

The registered resource provider plugin is responsible for the storage and retrieval of resource data, including filtering returned resources based on the supplied parameters.
This architecture allows for resource persistance to be tailored to the implementation requirements, either in the file system, a database service, cloud service, etc.

Server Resource API exposes the following methods to plugins:

1. Register resource provider plugin:

public register(pluginId: string, provider: ResourceProvider)

2. Un-register resource provider plugin:

public unRegister(pluginId: string)

3. Retrieve the resource of the defined type (routes, waypoints, etc.) with the supplied id.

public getResource(type:string, id:string): any

Resource providers:

These are plugins that implement the following interface:

resourceProvider: {
    types: Array<string>;  // ** resource types handled e.g. ['waypoints','routes', 'regions'],
    methods: {  // ** methods called to action requests
        listResources: (type:string, params:object):any=> Promise<any> 
        getResource: (type:string, id:string)=> Promise<any>
        setResource: (type:string, id:string, value:any)=> Promise<any> 
        deleteResource: (type:string, id:string)=> Promise<any> 
    }
}

The methods will be called for each resource type listed in the types array.

Each method returns a Promise which is resolved if successful and a rejected if unsuccessful.

[panaaj]

Added register() and unRegister() methods to the resourcesApi.
The plugin acting as resource provider would call:

• register() within the start() function
• unRegister() within the stop() function.

Operation:

register() will add reference(s) to the supplied plugin id, and provider methods for the resource type(s) defined. Once a resource type has a handler registered any subsequent registrations for the same resource type are ignored.

unRegister() will remove the provider methods for the supplied plugin id.

[panaaj]

@tkurki Should the resources API display in Connection & Plugin Status section of the server Dashboard display which plugins are handling with resource types?

[tkurki]

I don't think this is something I'd want on the dashboard. I'd imagine this is something you set up every once in a while, not something you'd check on the dashboard.

Maybe a section under the plugin list in Plugin Config? Or under each plugin entry in the list, grey out if the the pluing is not enabled?

[panaaj]

@tkurki @sbender9 Looking for advice..... as this PR currently stands a PUT to a resource path (./resources/routes/{id}) requires the data to be submitted under a "value" key in the body....e.g.

{
   value: { <resource data> }
}

This aligns with the current PUT requirement as per the spec.
This repesents a BREAKING CHANGE when it comes to the current operation of the sk-resource-fs plugin which expects the data to be directly in the body...e.g.

{
   name: 'route name',
   description: 'route description,
   distance: 80000,
   feature { ... }
}

So the question I have is .......
Should requests to resources paths align with PUT requests to other paths as per the current spec. OR
as there is now a Resource API defined, should this now be the preferred mode of operation and PUT, POST, DELETE operations are NOT allowed to the resource paths?

Given that the current PUT implementation does not service the ./resources/* paths directly (you need to PUT to ./vessels/self/resources/* for it to work) this is really green fields function so any breaking change would be to the way Freeboard-sk and the sk-resources-fs plugin have had to implement current functionality.

The impact to the end user would be that an updated version of Freeboard-sk and sk-resources-fs plugin aligned with the server realease containing the Resources API would need to be installed.

[tkurki]

Well, that question is: do we break in new APIs from "the data is actually in the value field" and "PUT is for actions" and use PUT and POST the way they are usually used in REST APIs. I think we have sort of painted ourselves in a corner with the full model, that necessitates the value structure.

To be honest I'd rather make a clear distinction between the old and new/revamped APIs and shed the baggage that we have there. Even if we'd have to start building v2 piecemeal.

[tkurki]

So is this PR going to result in an organised new way for plugins to register serving resources paths or that AND include the default implementation? The code so far does only the first part, right?

[tkurki]

I did a bit of reading here and commented here and there.

Please format with npm run lint. There's nothing here that is not auto-fixable, so CI lint is not complaining...need to fix that so that it does not succeed if there's stuff to fix.

[panaaj]

@tkurki This PR has been rebased following merge of #1358.
It is now very close for consideration to merge..... just wondering if the OpenApi stuff will make it into the server main branch?
If it will soon... where should this PR place the openapi.json file? Is it's current location OK?

[panaaj]

Supersceded by #1361