4. Service ngcp-comx-fs (comx-fileshare-service)

info
info	comx is a legacy name for the current RTC:engine component. The service comx-fileshare is the last not-yet-renamed component there. It has beed renamed to the service ngcp-comx-fs on Sipwise C5 long time ago but it still is being shipped as a package ngcp-comx-fileshare-service and stored in the Git repository comx-fileshare-service.git. It will be polished at some point in the future.

4.1. Overview

The ngcp-comx-fs is a Node.js based filesharing service and it is intended to be used via REST API. This service allows you to upload arbitrary files to the server and to download/share them with a generated link.

The API can be used with in 2 ways:

with simple identification, which means that only credentials of a user/subscriber are needed for authentication
with session identification, which also provides for example the time-to-live (TTL) functionality besides authentication, and will be used in combination with the RTC:engine.

4.2. Configuration and Usage

4.2.1. Change authentication method

To use Sipwise C5 subscribers as authentication against the API, you need to set it in the /etc/ngcp-comx-fileshare-service/config.js:

simpleUpload: {
  authentication: {
    enabled: true,
    subscriber: true,
    username: 'foo8',
    password: 'bar8'
  }
}

You can now authenticate like this with the API:

curl -i -X POST --insecure --form file=@/tmp/test.txt --user '43991002@domain.tld:x43991002' \
    https://$NGCP_IP:1446/rtc/fileshare/uploads

If you want to use the credentials from the config.js you need so set it to the following settings:

simpleUpload: {
  authentication: {
    enabled: true,
    subscriber: false,
    username: 'foo8',
    password: 'bar8'
  }
}

In this case, the login parameter would be this:

curl -i -X POST --insecure --form file=@/tmp/test.txt --user 'foo8:bar8' \
    https://$NGCP_IP:1446/rtc/fileshare/uploads

4.2.2. Database Structure

Table information for the fileshare MariaDB database:

downloads table:

Table E.1. Details of downloads Table in fileshare Database

Field Name	Field Type	Description
id	CHAR, PRIMARY KEY	Internal ID of the download action
state	ENUM	State of the download
uploaded_id	CHAR, FOREIGN KEY	External ID used for accessing the uploaded file in uploads table
created_at	DATETIME	Download action creation time
updated_at	DATETIME	Time of last download action modification

sessions table:

Table E.2. Details of sessions Table in fileshare Database

Field Name	Field Type	Description
id	CHAR, PRIMARY KEY	Internal ID of the session
ttl	INT	Time-to-live value of the session (in seconds)
created_at	DATETIME	Session creation time
updated_at	DATETIME	Time of last session modification

uploads table:

Table E.3. Details of uploads Table in fileshare Database

Field Name	Field Type	Description
id	CHAR, PRIMARY KEY	Internal ID of the file entry
data	LONGBLOB	The file data
original_name	VARCHAR	Original name of the file
mime_type	VARCHAR	MIME type of the file
size	INT	File size in bytes
ttl	INT	Time-to-live value of the file
state	ENUM	State of the file
session_id	CHAR, FOREIGN KEY	External ID used to access session data in sessions table
created_at	DATETIME	File creation / upload time
updated_at	DATETIME	Time of last file modification

4.3. Activation of Filesharing Service on NGCP

The service is installed on every Sipwise C5 system, but is not activated by default. In order to activate the service with default port 1446, connect with SSH and execute:

ngcpcfg set /etc/ngcp-config/config.yml fileshare.enable=yes
ngcpcfg apply 'Enabled ngcp-comx-fs'
ngcpcfg push all

and check the status with ngcp-service summary. The service ngcp-comx-fs should be now up and running.

4.4. Message Sequence Chart

4.4.1. Simple Message Sequence

Figure E.1. Sequence Simple

4.4.2. Detailed Message Sequence

Figure E.2. Sequence Detailed

4.5. API of Filesharing Service

4.5.1. HTTP Authentication

Type: Basic Auth
      username/password

4.6. Upload and Download with Simple Identification

The following HTTP methods can be used to perform file upload and download:

POST /uploads                                               // Simple upload

GET  /uploads/{fileId}                                      // Simple download

4.7. Upload and Download with Session Identification

The following HTTP methods can be used to perform file upload and download, and to manage sessions.

Session identification:

GET    /sessions/{sessionId}/files                            // Get all files of a session
GET    /sessions/{sessionId}/files/{fileId}/tokens/{tokenId}  // Download a single file

POST   /sessions                                              // Create a new session
POST   /sessions/{sessionId}/files                            // Create a new file entry
POST   /sessions/{sessionId}/files/{fileId}/tokens            // Generate a download token

PUT    /sessions/{sessionId}/files/{fileId}                   // Upload and store a file

Simple identification:

GET    /uploads/{fileId}                                      // Get uploaded file
POST   /uploads                                               // Upload file

4.8. Curl Example for Simple Upload Request

curl -i -X POST --insecure --form file=@/tmp/test.txt --user 'myuser@example.com:mypass' \
    https://$NGCP_IP:1446/rtc/fileshare/uploads

4.9. Upload Parameters

4.9.1. file

The parameter file defines the path to the desired file that should be uploaded.

caution
caution	This upload parameter is mandatory!

Curl example:

curl -i -X POST --insecure --form file=@/tmp/test.txt https://$NGCP_IP:1446/rtc/fileshare/uploads

4.9.2. user

The parameter user defines the user to authenticate with the fileshare service.

caution
caution	This upload parameter is mandatory!

curl -i -X POST --insecure --user 'foo:bar' https://$NGCP_IP:1446/rtc/fileshare/uploads

4.9.3. TTL

The parameter ttl defines the time-to-live (in seconds), that is how long the uploaded file will be available for download. The default values for this parameter are defined in the configuration file:

models: {
    session: {
        ttl: 86400 * 7
    },
    upload: {
        ttl: 3600
    }
}

Curl example:

curl -i -X POST --insecure --form file=@/tmp/test.txt --form ttl=3600 \
    --user 'foo:bar' https://$NGCP_IP:1446/rtc/fileshare/uploads

Response from curl when TTL is expired:

{
  "message": "upload expired"
}

Response in the log file when TTL is expired:

Error at /uploads/88e5905d-5d96-4750-ab3d-77a1ed26f569: message=upload expired, status=410

4.10. Number of Possible Downloads

There is a significant difference in the usage of the filesharing service between the approach within the RTC:engine and the simple upload/download one:

If you are using the simple upload and download approach, the generated download link you get for your file can be used as many times as required, as long as the TTL is not expired.
The approach with the Session ID, which will be used with the RTC:engine implementation, limits the download to one-time only. This means that the generated download link can be used only once. If you plan to share the URL with multiple persons, you have to generate one link for each recipient.