Create /api/v1/instance/:id/files/... api for basic CRUD operations

[joepavitt]

The Frontend will make API requests to an API provided by the platform that then proxies the requests to the launcher to get the response.

As such, the semantics of the platform API will need to mirror that implemented in the launcher via FlowFuse/nr-launcher#273

• The api will hang under /api/v1/projects/:instanceId/files/...
• It is an EE feature; the api should only be enabled for instances in teams that have the FileManagement feature enabled
• All operations should be available to owner and member roles - need to consider if viewer should have read-only access (ie list, but no rename/upload etc)
• As the files are stored on the instance, this API will be unavailable if the instance is suspended.

API Endpoints

We already have a file-system-like API for the shared-library endpoints. That was largely duplicated from the Node-RED api for managing libraries. It has some drawbacks, so I don't want to blindly copy its approach.

Care must be given to (and tests to verify) handling of unexpected / \ and .. appearing in filenames/paths.

• GET /api/v1/projects/:instanceId/files/_/:path - list files in a directory
• PUT /api/v1/projects/:instanceId/files/_/:path - update file/directory information (name/sharing info)
• POST /api/v1/projects/:instanceId/files/_/:path - create directory/upload file
• DELETE /api/v1/projects/:instanceId/files/_/:path - delete directory/file

GET /api/v1/projects/:instanceId/files/_/:path

Get a directory listing of :path. The response will be a collection object and support pagination (as per https://flowfuse.com/docs/contribute/api-design/#pagination).

This doesn't provide a recursive list - only the files/directories at :path (which will be relative to /data/storage on the instance itself).

{
    "meta": {
        "next_cursor": "",
    },
    "files": [
        {
            "type": "file",
            "path": "filename",
            "size": "1024",
            "lastModified": "2024-08-08T19:40:05.000Z"
        },
        {
            "type": "directory",
            "path": "filename",
            "lastModified": "2024-08-08T19:40:05.000Z",
            "share": { ... }
        }
    ],
    "count": 8
}

• Each entry in files has a type field to identify file vs directory.
• file type also have size
• directory type might also have share - meta data about how that folder is shared by Node-RED. Details below

If :path is not a directory that can be listed, the api will return 404. This means this end point cannot be used to get the file contents - that'll be handled separately.

PUT /api/v1/projects/:instanceId/files/_/:path

Update information about a file/directory. This will support the following tasks, based on the body received. This operations should be mutually exclusive.

Rename/Move

TBD: relative/absolute name

{
    path: "new filename"
}

Update sharing options

Only valid for directory objects; cannot modify sharing properties of a :path that represents a file.

{
    share: { ... }
}

POST /api/v1/projects/:instanceId/files/_/:path

Either create a directory or upload a file. I could be persuaded to separate these out somehow.. but for now...

Create directory

• Content-type: application/json
• Path is relative to :path and must not contain .. or /

{
    path: 'name of dir'
}

Create file

• Content-type: multipart/form-data
• Expect a form field called file containing the file data
• Open questions
  • filesize limit?

DELETE /api/v1/projects/:instanceId/files/_/:path

Delete the file/directory.

share setting

The share property contains the properties:

• root : the relative url the folder should be shared from (ref httpStatic in Node-RED configuration)

In future it can include any other settings supported by Node-RED - but root is the minimum requirement.

In the database, a new ProjectSetting will be used under the key staticAssets. This will be a single property containing information about all shared directories:

{
    "dashboard/images" : { "root": "/static/images" },
    "tps-reports" : { "root": "/reports"}
}

With the above example, an instance that is at https://nr1.example.com will serve:

• /data/storage/dashboard/images as https://nr1.example.com/static/images
• /data/storage/tps-reports as https://nr1.example.com/reports

So a file stored in /data/storage/dashboard/images/header/logo.png will be served as https://nr1.example.com/static/images/header/logo.png

The launcher will use this settings to set the httpStatic property of the Node-RED settings file. (PRs open for this - see task list below).

Tasks

Preview Give feedback

1. Implement files api #4384
   +0
2. First pass at file api nr-launcher#275
   +0
   
3. Add initial file api driver-localfs#144
   +0
4. First pass files api for docker driver-docker#108
   +0
   
5. First pass at file api for k8s driver-k8s#175
   +0
   
6. Expose httpStatic settings on instance settings route #4388
   +0
7. Config httpStatic based on instance settings nr-launcher#276
   +0

[knolleary]

Have updated the description with an initial API spec to work from. This will be the basic structure used in the launcher as well.

[knolleary]

Updated with description of the share property.

[hardillb]

I think there is an error in the sample above, each file object should have name not path

{
    "meta": {
        "next_cursor": "",
    },
    "files": [
        {
            "type": "file",
            "path": "filename",
            "size": "1024",
            "lastModified": "2024-08-08T19:40:05.000Z"
        },
        {
            "type": "directory",
            "path": "filename",
            "lastModified": "2024-08-08T19:40:05.000Z",
            "share": { ... }
        }
    ],
    "count": 8
}

should be

{
    "meta": {
        "next_cursor": "",
    },
    "files": [
        {
            "type": "file",
            "name": "filename",
            "size": "1024",
            "lastModified": "2024-08-08T19:40:05.000Z"
        },
        {
            "type": "directory",
            "name": "filename",
            "lastModified": "2024-08-08T19:40:05.000Z",
            "share": { ... }
        }
    ],
    "count": 8
}

[joepavitt]

Task Completed