File Service Client

<bk-file-client></bk-file-client>

The File Service Client manages http requests towards an instance of Mia Files Service to upload, download, store files.

Further details on how Back-Kit components can be composed to handle file fields are available in the specific section.

How to configure

To configure the File Service Client, property basePath should be specified. basePath is the base path of the URL to which HTTP requests are sent, i.e. the endpoint targeting the Files Service.

{
  "tag": "bk-file-client",
  "properties": {
    "basePath": "/files"
  }
}

Download and Preview File

When a component signals the need to download a file (that is, emits a download-file event), the File Service Client by default performs a GET request to /download/<file-name>. Upon successful download, an deleted-file event is emitted, else an error event.

However, if the meta field of the download-file event has key showInViewer set to true, the File Service Client attempts to fetch the file and, in case of success, notifies via show-in-viewer event that the file needs to be previewed, else notifies the failure with an error event. A component such as the Pdf Viewer could pick up the show-in-viewer request. If meta field showInViewer in download-file meta is set to "skip-checks", the File Service Client does not attempt to download the file, but rather immediately signals the request for the file to be previewed.

Query Parameters Tuning

Property queryParams handles how the file is downloaded, in compliance with Files Service specifications

{
  "download": 1,
  "downloadWithOriginalName": 1,
  "useOriginalName": 1
}

Parameter download and downloadWithOriginalName are used when downloading the file, while parameter useOriginalName is used to fetch a file which should be previewed rather than downloaded.

Upload and Delete Files

The File Service Client acts as a proxy between rendering components and the Files Service, facilitating the communication and interaction between the two. It is designed to handle various types of events that may be received from other components, leading to HTTP requests being made to the Files Service. These events include:

• Upload File When a upload-file event is received, the File Service Client sends a POST request to its base path with a multipart body containing the file form the payload of the event, aiming at uploading the file to the file storage service. In case the meta field of the event includes extra information (metaData), this is also included in the body of the POST request. Upon successful upload, an uploaded-file event and a success event are emitted, else an error event.

• Delete File When a delete-file event is received, the File Service Client sends a DELETE request to /<file-name>, where the name of the file is taken from the payload of the event, aiming at removing the file from the file storage service. Upon successful deletion, an deleted-file event and a success event are emitted, else an error event.

Fetch all Files

Beginning from Files Service version 2.7.0, route /files is available. Reaching this route with a GET request allows to retrieve the list of files metadata handled by the Files Service. Data fetched in this way are paginated.

The following query parameters can be appended to the GET

• limit: number of items to be fetched per page
• page: number of pages to skip
• dateFrom: filters out all files that were updated afterwards

Upon receiving a fetch-files event, the File Service Client triggers a GET to /files, appending query parameters as specified in the payload of the event.

Rerouting HTTP requests

Property reroutingRules allows to reroute HTTP calls based on the their pathname and HTTP method.

reroutingRules is an shaped like an array of objects with keys from and to.

• key from allows to specify two strings that are matched against the url pathname and HTTP method of the request
• key to allows to specify a string, being the URL pathname to which the request is redirected

Each emitted HTTP request is matched against all rules using its from key. The request is rerouted to the value specified in the to key of first macthing rule. Requests that match no rule are not redirected.

info

If key from of an entry of reroutingRules is a string, all HTTP methods will be matched.

The regular expression specified in the from key of an entry of reroutingRules may include groups, which can be referenced in the to key using the character "$" and the index of the group or its name.

{
  "reroutingRules": [
    {
      "from": {
        "url": "/files/",
        "method": "POST"
      },
      "to": "/upload-file/"
    },
    {
      "from": {
        "url": "/files/download/([^/]+)",
        "method": "GET"
      },
      "to": "/download/$1"
    }
  ]
}

Examples

Example: Download File

A File Service Client configured like the following:

{
  "tag": "bk-file-client",
  "properties": {
    "basePath": "/files"
  }
}

upon listening to a download-file event with payload

{
  "file": "avatar.jpg"
}

triggers a GET call to /files/download/avatar.jpg with query parameters

{
  "download": 1,
  "downloadWithOriginalName": 1
}

Example: Query Parameters

The File Service Client allows to configure the query parameters to be included in the HTTP call that is performed to download a file through property queryParams.

A File Service Client configured like the following:

{
  "tag": "bk-file-client",
  "properties": {
    "basePath": "/files",
    "queryParams": {
      "downloadWithOriginalName": 0
    }
  }
}

upon listening to a download-file event with payload

{
  "file": "avatar.jpg"
}

triggers a GET call to /files/download/avatar.jpg with query parameters

{
  "download": 1,
  "downloadWithOriginalName": 0
}

Example: Show in viewer

A File Service Client configured like the following

{
  "tag": "bk-file-client",
  "properties": {
    "basePath": "/files"
  }
}

upon listening to a download-file event with this payload and meta:

{
  "payload": {
    "file": "avatar.jpg"
  },
  "meta": {
    "showInViewer": true
  }
}

attempts to download the file and, on success, emits a show-in-viewer event with payload:

{
  "url": "<page-domain>/files/download/avatar.jpg?useOriginalName=1"
}

Depending on the showInViewer value in meta, the File Service Client has different behaviors:

• "showInViewer": true: it attempts to download the file and, on success, emits a show-in-viewer event.
• "showInViewer": "skip-checks": it emits a show-in-viewer event, without first attempting to download the file.

info

If the plugin orchestration is managed by micro-lc (version 2 or higher) and showInViewer is true, headers configured in the micro-lc configuration are forwarded, while if showInViewer is skip-checks, they are not.

Example: Fetch File List

A File Service Client configured like the following:

{
  "tag": "bk-file-client",
  "properties": {
    "basePath": "/file-service"
  }
}

upon listening to a fetch-files event with payload

{
  "limit": 20,
  "page": 2
}

triggers a GET call to /file-service/files/ with query parameters identical to the payload of the event

{
  "limit": 20,
  "page": 2
}

Example: Upload File

A File Service Client configured like the following:

{
  "tag": "bk-file-client",
  "properties": {
    "basePath": "/files"
  }
}

upon listening to a upload-file event with payload

{
  "file": {
    ... // file to upload
  }
}

and meta

{
  "metaData": {
    "fileOwner": "Andrew"
  }
}

triggers a POST call to /files/ with a multipart body translation to the payload of the event as well as the extra information inside meta.metaData

{
  "file": {
    ... // file to upload
  },
  "fileOwner": "Andrew"
}

Example: Delete File

A File Service Client configured like the following:

{
  "tag": "bk-file-client",
  "properties": {
    "basePath": "/files"
  }
}

upon listening to a delete-file event with payload

{
  "file": "avatar.jpg"
}

triggers a DELETE call to /avatar.jpg

Example: Reroute HTTP Requests

A File Service Client configured like the following:

{
  "tag": "bk-file-client",
  "properties": {
    "basePath": "/files",
    "reroutingRules": [
      {
        "from": {
          "url": "/files/download/([^/]+)",
          "method": "GET"
        },
        "to": "/download/$1"
      },
      {
        "from": {
          "url": "/files/",
          "method": "POST"
        },
        "to": "/upload-file/"
      }
    ]
  }
}

requests to download a file form the path "/download/" instead of the default "/files/download/", and to upload a file from the path "/upload-file/" instead of the default "/files/".

The HTTP request triggered to download a file would normally be a GET call against the "/files/download/name-of-the-file" path. This call matches the first entry of reroutingRules; therefore, it is rerouted to "/download/name-of-the-file". Notice how the "$" character can be used in the target path to reference groups captured in the regular expression specified inside from.url.

The HTTP request to upload a file would normally be a POST call directed to "/files/". Such a request is intercepted by the second rule specified in reroutingRules and redirected to "/upload-file/".

API

Properties & Attributes

property	attribute	type	default	description
basePath	-	string	-	the URL base path to which to send HTTP requests
headers	-	{[key: string]: string}	-	headers to add when an HTTP request is sent
credentials	-	'include'|'omit'|'same-origin'	-	credentials policy to apply to HTTP requests
queryParams	-	QueryParams	{"download": 1,"downloadWithOriginalName": 1, "useOriginalName": 1}	query parameters to be passed to the Files Service, according to its interface
reroutingRules	-	ReroutingRule[]	-	rules to redirect HTTP request to new routes

QueryParams

interface QueryParams {
  download: 0 | 1
  downloadWithOriginalName: 0 | 1
  useOriginalName: 0 | 1
}

ReroutingRule

type ReroutingRule = {
  from: string | { url: string, method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE' }
  to: string
}

Listens to

event	action	emits	on error
upload-file	sends a POST request to upload a file	uploaded-file, success	error
download-file	sends a GET request to download/preview a file	downloaded-file, success	error
delete-file	sends a DELETE request to remova a file from storage	deleted-file, success	error
fetch-files	sends a GET request to fetch uploaded files from storage	fetched-file, success	error

Emits

event	description
uploaded-file	notifies successful file upload
downloaded-file	notifies successful file download
deleted-file	notifies successful file deletion
show-in-viewer	requests to preview a PDF file inside a viewer
success	notifies successful HTTP request
error	contains http error messages when something goes wrong