Skip to content
No description, website, or topics provided.
JavaScript
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
db
docs
gateway
logger
.env
.gitignore
.snyk
.travis.yml
CONDUCT.md
CONTRIBUTING.md
README.md
index.js
package.json
swagger.yaml

README.md

Build Status Known Vulnerabilities JavaScript Style Guide

NEWTON BANNER

Fab Lab Modules: Fab Lab Wrapper (Pi-Gateway) APIs

This software is part of a larger suite of microservices designed to remotely manage digital fabrication equipment in a loosely coupled and distributed environment. More specifically, the software in this repo implements a wrapper for the Fab Lab APIs with basic security policies. Fab Lab machines are not directly exposed to the internet, but rather they are protected by a Gateway which is the entry point to Fab Lab fabrication resources. The Gateway is responsible for managing Fab Lab access, routing incoming fabrication requests to available machines and interacting with the Cloud Hub to control fabrication status. The Fab Lab APIs wrapper has be designed to work either as a standalone application or behind a more feature-rich and general-purpose gateway as, for example, Express Gateway. All the Gateway software infrastructure can be orchestrated by a CLI that at the moment has not been open-sourced; however, the CLI is not necessary to control the Fab Lab APIs wrapper.

About

This software has been developed by Gianluca Cornetta and Javier Mateos within NEWTON project. NEWTON is a large scale Integrated Action, started in March 2016 and scheduled to end in summer 2019, funded by the European Commission under the Horizon 2020 Researh and Innovation Programme with grant agreement n. 688503.

Table of contents

  1. Preliminary steps
  2. Software and Infrastructure description
  3. Documentation and developer support
  4. Websites
  5. Contribution guidelines
  6. License

Preliminary steps

Before installing the software you have to make sure that you comply with the hardware and software requirements specified in the next two sections.

Hardware prerequisites

This software has been tested on a Raspberry Pi III Model B (amrv7 32-bit architecture) with a 8-GByte SD card. You need at least 150 MBytes of free disk space to install the software.

Software prerequisites

The Machine wrapper software requires that you previously install on your system the following software packages:

  1. Node.js >= v8.x
  2. npm >= v6.0.x
  3. Redis v4.x
  4. Express Gateway v1.x (optional)

We have not tested the software with Redis latest version; however it should work without any problem if you update redis client to the last version in the `package.json` file with the project dependencies.

Installation

To install the Fab Lab APIs Wrapper module go through the following steps:

  1. download or clone this repo,
  2. run npm install in the installation folder,
  3. run npm run start to start the service.

The server listen to port 3000 of your Raspberry Pi.

If you plan to use the Fab Lab APIs Wrapper software behind Express Gateway you should configure Express Gateway to redirect all the incoming requests to localhost:3000. Please, refer to this link in order to suitably configure Express Gateway.

Software and infrastructure description

The Fab Lab APIs Wrapper (i.e. the Pi-Gateway) has been designed as an independent microservice that acts at the Fab Lab Gateway backend. The software implements features to communicate and control the Fabrication Machine Wrappers (i.e. the Pi-Wrappers). The Pi-Gateway relies on Redis to keep the status of the Fab Lab (running fabrication batches, machine status, user quotas, etc.)

Running npm behind a proxy

All the Fab Lab management software has been written entirely in JavaScript using Node.js as the server-side platform. In Node.js, dependencies and package installation and updating is managed through the Node Packet Manager (npm). When Node.js is deployed behind a proxy npm must be suitably configured in order to work correctly.

In our specific case, the Fab Lab has been deployed in a complex enterprise network set-up that is not managed by us, but by the system administrators of our University. This means that the Pi-Gateway has neither a public IP address nor a direct access to the internet. If this is not your case, probably these considerations will not apply to you and you may skip this section.

Deploying the Fab Lab infrastructure in an enterprise network that is not managed by you, could result particularly challenging. More specifically, in our case:

  • The Pi-Gateway has no direct Internet access necessary to reach the Cloud Hub infrastructure.
  • The Cloud Hub is tightly integrated with AWS managed services and uses Route 53 for name resolution (DNS). Unfortunately, this service is not visible from the VPN tunnel; thus, a lightweight DNS service (Dnsmasq) must be deployed on the cloud side of the infrastructure to resolve network names into IP addresses,

  • HA-Proxy, that is used to load balance the incoming requests among the services deployed on the cloud infrastructure, cannot work as a forward proxy; thus, it is necessary to the deploy on the cloud end also a lightweight proxy service (Timyproxy) in order to forward to the internet the requests coming from the Pi-Gateway.

Fig. 1 depicts the cloud architecture and services to allow outgoing requests from the Pi-Gateway to the internet. Observe that the Fab Lab Gateway is a router/firewall that belongs to the enterprise network. It is not part of the Fab Lab infrastructure and is managed by the our University network administrators.

CLOUD ARCHITECTURE

Fig. 1 - Cloud Configuration to Support Internet Access from the Pi-Gateway.

Once the DNS and proxy services have been correctly configured, the npm package installed on the Pi-Gateway must be configured as well in order to correctly operate behind a proxy. This can be done by either using the npm command line interface or directly editing with your favourite editor the .npmrc file located in the Pi-Gateway home directory specifying the URL and listening port of the proxy service. Please, observe, that in the VPN configuration of Fig. 1 all the services communicate using private IP addresses. The configuration file is reported in the sequel:

proxy=http://<proxy_private_ip_address>:<proxy_port_number>
https-proxy=http://<proxy_private_ip_address>:<proxy_port_number>
strict-ssl=false
ca=null
registry=http://registry.npmjs.org

Some Tinyproxy limitations

Tinyproxy is a lightweight proxy service easy to install, deploy and configure. However, there is a limitation when used with the Fab Lab APIs Wrapper. The APIs Wrapper supports both HTTP and HTTPS connection. Unfortunately, this HTTPS connections cannot be used with the actual software infrastructure because Tinyproxy does not accept incoming HTTPS connections. HTTPS connections in Tinyproxy are only supported using the CONNECT method which implies that the browser/client must know a-priori it is talking to a proxy server and use CONNECT to implement a connection.

This indeed is not a security issue since the information is already encrypted in the IPSec tunnel that connects the Fab Lab to the cloud infrastructure; however, if one would like to implement a transparent proxy supporting also HTTPS connection, Squid can be used instead of Tinyproxy. Nonetheless, Squid is not so easy to configure and deploy as Tinyproxy is.

Documentation and developer support

The Fab Lab software infrastructure has been designed with the developer in mind. For this reason, Swagger has been integrated into the Pi-Gateway and the Pi-Wrapper middleware. This allow the developer to have on-line access to the API documentation and to test the native APIs through the Swagger User interface (Swagger UI). In addition, the API-first approach used to the develop the Fab Lab software allows to easily expand the software, the protocol stack and add new features adding new layers on top of the native APIs without the need of modifying the core software architecture.

Fab Lab APIs

Fab Lab APIs expose the underlying digital fabrication machines as software service that can be accessed from the Cloud Hub. These APIs are the entry point for the Fab Lab infrastructure and provide software methods that can be exploited to remotely control and monitor the digital fabrication machines using the cloud application interfaces. The Fab Lab APIs implement methods to get Fab Lab status and API quota, to delete a job submitted for fabrication and to send a fabrication request. Table 1 displays the resource URI and the implemented HTTP verbs for the Fab Lab APIs.

Table 1: Fab Lab APIs
Resource GET POST PUT DELETE
/fablab Shows the Fab Lab information Error 400
(Bad Request)
Error 400
(Bad Request)
Error 400
(Bad Request)
/fablab/quota Shows the available API quota of the Fab Lab Error 400
(Bad Request)
Error 400
(Bad Request)
Error 400
(Bad Request)
/fablab/jobs/status/1234 Show the status
of the job with
id=1234
Error 400
(Bad Request)
Error 400
(Bad Request)
Error 400
(Bad Request)
/fablab/jobs?user=123&machine=laser%20cutter&process=cut&material=wood Error 400
(Bad Request)
Submit a job
to a fablab specifying the user the machine types and the fabrication parameters in the query string
Error 400
(Bad Request)
Error 400
(Bad Request)
/fablab/jobs/1235 Error 400
(Bad Request)
Error 400
(Bad Request)
Error 400
(Bad Request)
Delete the job
whose id is specified in the URL path

Versioning

API versioning is not mandatory for Fab Lab APIs.

Supported formats

Fab Lab APIs exclusively support JSON format.

Error management

The API error codes will match HTTP codes. The following cases are managed:

  1. Everything worked (success): 200–OK.
  2. The application did something wrong (client error): 400–Bad Request.
  3. The API did something wrong (server error): 500–Internal Server Error.

In the case of client and server error, the server will return in the response a JSON object with error details and hints to correct it. The message has the following format:

{code: the error code, message: the error message, details: the error details}

Table 2 reports error codes and details.

Table 2: Fab Lab API Wrapper Error Codes
Error Code Error Details
1 Fab Lab communication error
2 Database error
3 The Fab Lab object has not been built yet
4 Unknown authorization error
5 Unknown machine error
6 Database error. Cannot read
7 Fab Lab busy
8 Database error. Cannot write
9 API quota consumed
10 Cannot connect to target machine
11 Undefined user
12 Undefined machine
13 Invalid route. Job not in database
14 Database error. Cannot delete

On-line documentation

The Fab Lab APIs documentation can be accessed from the Fab Lab network at the following URL:

http://gateway_name.local:3000/docs

This URL leads to the Pi-Gateway API documentation landing page depicted in Fig. 2. Please note that Swagger UI HTML code is linked to external stylesheets and javascript code; thus you must ensure your network has external connectivity in order to use this feature.

API DOCUMENTATION LANDING PAGE

Fig. 2 - The API Documentation Landing Page.

The documentation page allows navigating through the API paths and allowed HTTP verbs; for example, the screenshot of Fig. 3 depicts the documentation page of the API invoked by executing a GET request to the Fab Lab Gateway base URL.

API DOCUMENTATION

Fig. 3 - API Documentation for a GET Request to the Gateway Base URL.

The page shows the API description and an example of API response with 200 status code. In the case of API with content negotiation, the interface also allows selecting the response type. Finally, the interface has a “Try it out” button that allows to perform a request to the API and check the response in the web user interface. When the “Try it out” button is pressed, the user is redirected to another page that allows to submit to the API, query string parameters, forms, files, etc. (see Fig. 4). In the case of Fig. 4, the API call is very simple and has no parameters.

API SUBMISSION FORM

Fig. 4 - API Call Submission Form.

Finally, Fig. 5 depicts the API response obtained after pressing the execute button.

API RESPONSE

Fig. 5 - Example of Gateway API Response.

APIs responses

Tell me about the Fab Lab

GET /fablab

Response:

200 OK
{
“fablab”: {
  “id”: 1234
  .... 
},
 “jobs”: {
  ....
 }
}

Tell me about the Fab Lab quota

GET /fablab/quota

Response:

200 OK
{
“id”: 1234,
“quota”: 2000
}

Submit a job

POST /fablab/jobs?user=1234&machine=laser%20cutter&process=cut&material=wood

Response:

200 OK
{
“id”: 1234,
“mId”: 3456,
“jobId”: 4567
}

Recall, that with this method a design file in PNG format is uploaded on the server. Our API specifications correspond to the HTTP request depicted below.

POST /fablab/jobs
Host: pigateway.local/public/uploads
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryqzByvokjOTfF9UwD
Content-Length: 204

------WebKitFormBoundaryqzByvokjOTfF9UwD
Content-Disposition: form-data; name="design"; filename="design.png"
Content-Type: image/png

File contents go here.

------WebKitFormBoundaryqzByvokjOTfF9UwD--

Tell me about a job

GET /fablab/jobs/1234

Response:

200 OK
{
   “id”: 1235
 
}

Cancel a job

DELETE /fablab/jobs/1235

Response:

200 OK

Websites

  1. Newton Fab Labs on Github
  2. Newton Project Page

Contribution guidelines

Please see CONTRIBUTING and CONDUCT for details.

License

This software is licensed under MIT license unless otherwise specified in the third-party modules included in this package.

You can’t perform that action at this time.