|
|
@@ -1,10 +1,10 @@
|
|
|
-Uppy Server is the server side component for Uppy. It is currently built with the Express.js.
|
|
|
-The purpose of Uppy Server is to interface with third party APIs and handle remote file uploading from them.
|
|
|
+Companion is the server side component for Uppy. It is currently built with the Express.js.
|
|
|
+The purpose of Companion is to interface with third party APIs and handle remote file uploading from them.
|
|
|
|
|
|
# How it works
|
|
|
|
|
|
## oAuth with Grant, Sessions
|
|
|
-Uppy Server uses an oAuth middleware library called `Grant` to simplify oAuth authentication.
|
|
|
+Companion uses an oAuth middleware library called `Grant` to simplify oAuth authentication.
|
|
|
Inside of `config/grant.js`, you configure the oAuth providers you wish to use, providing things like client key,
|
|
|
client secret, scopes, and the callback URL you wish to use. For example:
|
|
|
|
|
|
@@ -53,7 +53,7 @@ There are 5 controllers:
|
|
|
These controllers are generalized to work for any provider. The provider specific implementation code for each provider can be found under `server/providers`.
|
|
|
|
|
|
## Adding new providers
|
|
|
-To add a new provider to Uppy Server, you need to do two things: add the provider config to `config/grant.js`, and then create a new file in `server/providers` that describes how to interface with the provider's API.
|
|
|
+To add a new provider to Companion, you need to do two things: add the provider config to `config/grant.js`, and then create a new file in `server/providers` that describes how to interface with the provider's API.
|
|
|
|
|
|
We are using a library called [purest](https://github.com/simov/purest) to make it easier to interface with third party APIs. Instead of dealing with each and every single provider's client library/SDK, we use Purest, a "generic REST API client library" that gives us a consistent, "generic" API to interface with any provider. This makes life a lot easier.
|
|
|
|
|
|
@@ -64,19 +64,19 @@ Since each API works differently, we need to describe how to `download` and `lis
|
|
|
This whole approach was inspired by an example from `purest 2.x`. Keep in mind that we're using `3.x`, so the API is different, but here is the example for reference: https://github.com/simov/purest/tree/2.x/examples/storage
|
|
|
|
|
|
## WebSockets
|
|
|
-Uppy Server uses WebSockets to transfer `progress` events to the client during file transfers. It's currently only set up to transfer progress during Tus uploads to the target server.
|
|
|
+Companion uses WebSockets to transfer `progress` events to the client during file transfers. It's currently only set up to transfer progress during Tus uploads to the target server.
|
|
|
|
|
|
When a request is made to `/:provider/get` to start a transfer, a token is generated and sent back to the client in response. The client then connects to `wss://your-server/whatever-their-token-is`. Any events that are emitted using the token as the name (i.e. `emitter.emit('whatever-their-token-is', progressData)`) are sent back to the client.
|
|
|
|
|
|
WebSockets aren't particularly secure, but we feel this is safe because the token is only usable during the corresponding file transfer, and no sensitive information is being sent, only a file id and the progress.
|
|
|
|
|
|
# Design Goals
|
|
|
-These are the goals I had in mind while designing and building Uppy Server.
|
|
|
+These are the goals I had in mind while designing and building Companion.
|
|
|
|
|
|
## Standalone Server / Pluggable Module
|
|
|
-Uppy Server currently works as a standalone server. It should also work as a module that can easily be incorporated into an already existing server, so people don't have to manage another server just to use Uppy.
|
|
|
+Companion currently works as a standalone server. It should also work as a module that can easily be incorporated into an already existing server, so people don't have to manage another server just to use Uppy.
|
|
|
|
|
|
-One issue here is that `Grant` has different versions for Koa, Express, and Hapi. We're using `grant-express` right now, and also use all express modules. This becomes a problem if someone is using Koa, or Hapi, or something else. I don't think we can make Uppy Server completely framework agnostic, so best case scenario would be to follow Grant and make versions for Koa, Hapi, and Express.
|
|
|
+One issue here is that `Grant` has different versions for Koa, Express, and Hapi. We're using `grant-express` right now, and also use all express modules. This becomes a problem if someone is using Koa, or Hapi, or something else. I don't think we can make Companion completely framework agnostic, so best case scenario would be to follow Grant and make versions for Koa, Hapi, and Express.
|
|
|
|
|
|
All of this may be more trouble than it's worth if no one needs it, so I'd get some community feedback beforehand.
|
|
|
|
Ifedapo Olarewaju