@gigster/module-loopback-file-upload
v1.2.3
Published
Role | Name | Email | Slack ---- | ---- | ----- | ----- *Product Owner* | Frances Haugen | [[email protected]](mailto:[email protected]) | [@frances] *Maintainer* | Jerome Curlier | [[email protected]](mailto:[email protected]) | [@jerome] *Contribu
Downloads
76
Readme
loopback-file-upload
Role | Name | Email | Slack ---- | ---- | ----- | ----- Product Owner | Frances Haugen | [email protected] | [@frances] Maintainer | Jerome Curlier | [email protected] | [@jerome] Contributor | Samuel Gordalina | [email protected] | [@sam]
Overview
This module provides file upload for Loopback.
The module is using the Loopback Storage component. Please therefore review this component documentation to learn about this module.
The LoopBack storage component makes it easy to upload and download files to cloud storage providers and the local (server) file system.
- Amazon
- Azure
- Google Cloud
- Openstack
- Rackspace
- Local filesytem
Usage
- name: loopback-file-upload
location: 'npm:@gigster/[email protected]'
spec:
minSize: 0
maxSize: 20971520
storage: filesystem
containerName: uploads
Specification
Name | Status
---- | -----
containerName
| the name of the folder or bucket to store the files into.
minSize
| Minimum size of the file in bytes.
maxSize
| Maximum size of the file in bytes.
storage
| Which storage to use for the component, currently filesystem
and amazonS3
are supported.
Uploadable model definition
A model is uploadable
when it has the file-upload.uploadable
tag.
By default, the uploadable
model should have the following attributes.
Name | Status
---- | -----
filename
| the uniquely generated filename.
displayName
| the original file name.
url
| the URL location to download the file.
size
| the size of the file in bytes.
mimeType
| the mime type for the file.
created
| the date/time the file was uploaded.
Note: if you would like to change the list of attributes, you will need to update the uploader mixin generated code. The method storeFile
is returning the upload object to be stored for the uploaded file.
This is an example of a uploadable
model.
name: upload
public: false
properties:
- name: filename
type: string
- name: displayName
type: string
- name: url
type: string
- name: size
type: number
- name: mimeType
type: string
- name: created
type: date
relations:
- name: profilePhoto
type: hasOne
model: user
foreignKey: profilePhotoId
- name: userPhotos
type: hasMany
model: user
through: userPhoto
foreignKey: photoId
- name: productDocument
type: hasMany
model: product
through: productDocument
foreignKey: documentId
tags:
- file-upload.uploadable
Endpoints
The module create a POST
endpoint for each relation to an uploadable
model.
Endpoint | Method | Description
---- | ---- | -----
POST /model/relation/upload
( for example /user/profilePhoto/upload
) | relationUpload | Uploads a file
The following information is returned for each uplodaded file.
{
"filename": "ae99c364-0218-4a33-a5e3-3fdb6e07e817.json",
"displayName": "workspace.json",
"size": 148841,
"lastModified": "2017-11-22T20:15:15.376Z",
"url": "http://0.0.0.0:3000/storage/uploadsBucket/ae99c364-0218-4a33-a5e3-3fdb6e07e817.json",
"id": 47
}
We can then display the file using the URL provided.
Sample CURL commands
curl --request POST \
--url http://localhost:3000/api/users/1/profilePhoto/upload \
--header 'content-type: multipart/form-data; boundary=---011000010111000001101001' \
--form file=
Environment variables
Name | Description ---- | ----- GIG_MAX_UPLOAD_SIZE | Maximum size of the file (checked by the storage component) AWS_REGION | AWS region key when using AWS AWS_KEY | AWS key when using AWS AWS_SECRET_KEY | AWS secret key when using AWS
Dependencies
The loopback-file-upload depends on the loopback-models module. The loopback-models module should be defined before loopback-file-upload in the gig.yaml.
The following npm packages are used:
npm | version
---- | -----
loopback-component-storage
| ^3.3.1
Generation
Mixin
The Uploader
mixin is added to the project. The mixin attaches an upload
method to each relation defined in the mixin configuration, handles the file upload to the storage and store the file information in the uploadable
model.
Models
For each relation to a uploadable
model, the module contributes the upload
endpoint. The endpoint is attached to the model through a mixins configuration in the model json file.
For example:
"Uploader": {
"relations": [
"profilePhoto",
"photos"
]
}
The module also disable methods related to the uploadble
methods.
For a many
relationship, the following methods are disabled:
prototype.__create__relation_name
prototype.__update__relation_name
prototype.__updateById__relation_name
prototype.__link__relation_name
prototype.__unlink__relation_name
Otherwise, for a one
relationship:
prototype.__create__relation_name
prototype.__update__relation_name
where relation_name
is the name of the relation.
For example, for a user model having one profile photo and many photos:
"SetupRemoteMethods": {
"disable": [
"prototype.__create__profilePhoto",
"prototype.__update__profilePhoto",
"prototype.__create__photos",
"prototype.__update__photos",
"prototype.__updateById__photos",
"prototype.__link__photos",
"prototype.__unlink__photos"
]
},
Configuration
The following configuration is added to the Loopback configuration.
"upload": {
"containerName": "uploadsBucket",
"minSize": 0,
"maxSize": 20971520
}
This is based on the module configuration.
Storage
Filesystem
The file are stored under the folder name provided by the configuration in the storage folder. The default folder name is uploads
.
The files are then available through the url http://0.0.0.0:3000/storage/uploads/unique-file-identifier
.
AWS
The file are stored in the bucket provided by the configuration. The default folder name is uploads
.
The files are then then available through the AWS url.
Troubleshooting
DEBUG=loopback:file-upload:* yarn start