simplidefense-sdk-js

Introduzione

L'ecosistema SimpliDefense realizza una rete THCP tramite protocollo MQTT e, in aggiunta a questa, prevede la possibilità di integrare microservizi customizzati. Tali microservizi sono fruibili dall'app mobile.

Architettura

erDiagram
  Microservizio }o--|| THCP-Node : MQTT
  THCP-Node ||--o{ SimpleDefense-App : MQTT
  SimpleDefense-App }o--o{ Microservizio : HTTP

I microservizi utilizzano i nodi THCP per pubblicare la propria configurazione, ovvero i suoi entrypoint e quali dati questi richiedono. Il resto della comunicazione avviene in maniera diretta tramite il protocollo HTTP e REST API.

Le app mobile che si interfacciano con i microservizi agiscono in maniera automatica inviando aggiornamenti dei dati richiesti dalla configurazione.

Configurazione

Quando il microservizio è pronto a servire le app mobile, per essere visibile, deve pubblicare la sua configurazione sulla rete THCP. Per far ciò è necessario che il microservizio negozi con la rete un ID di servizio e riceva in cambio un token perenne per l'accesso al nodo.

Per mezzo di questo token è possibile pubblicare messaggi al topic services/{ID di servizio}. Qui dev'essere pubblicata la configurazione.

La configurazione è una stringa in formato JSON rappresentante un oggetto che deve rispettare lo schema definito nel file configuration.schema.json.

Nella configurazione è possibile parametrizzare il path degli entrypoint con la notazione {...} (es. /api/unit/{unit}). I possibili parametri utilizzabili sono i seguenti:

• unit Identificativo dell'unità interessata.
• line Identificativo della linea interessata.

Entrypoint

Identificazione utente

Ogni richiesta inviata dalle app mobile riporta, nell'header Authorization, l'identity token dell'utente che invia la richiesta. Tale identity token segue il formato previsto dallo standard OIDC e prevede un claim aggiuntivo acl. Questo claim riporta tutti i topic al quale l'utente può sottoscriversi o pubblicare e attraverso di esso è possibile determinare il tipo di autorizzazioni che un utente ha rispetto ad una certa unità. A seguire un esempio del contenuto di tale claim.

{
  ...
  "acl": {
    "pub": [
      "123456789/line/+/+",
      "123456790/line/1/activation",
      "123456790/line/1/deactivation",
      "123456790/line/2/activation",
    ],
    "sub": [
      "123456789",
      "123456789/line/+",
      "123456790",
      "123456790/line/1",
      "123456790/line/2",
    ],
    "all": []
  },
  ...
}

Il claim acl permette di individuare le autorizzazioni di un utente, il quale è invece identificato dal claim sub.

Risposte previste

Laddove non si è presentato un errore, ad una richiesta deve corrispondere una risposta con status 200, nel cui payload sono contenuti eventuali dati aggiuntivi da fornire all'utente.

Se invece si presenta un errore nell'esecuzione della richiesta, è necessario fornire una risposta il cui status rispetta questa leggenda:

• 400 Richiesta malformata o payload non valido.
• 401 Identity token mancante o non valido.
• 403 Identity token non autorizzato per l'unità richiesta.

Per i restanti errori è lasciata allo sviluppatore del microservizio la scelta dello status da utilizzare.

Queste risposte di errore devono però presentare un corpo ben definito, in formato JSON. Esso deve prevedere una descrizione della richiesta e dell'errore. A seguire un esempio in cui è mostrato l'utilizzo di tutti i campi obbligatori.

{
  "timestamp": "2019-09-16T22:14:45.624+0000",
  "status": 500,
  "error": "Internal Server Error",
  "message": "Descrizione dell'errore",
  "path": "/api/unit/1"
}

Requisiti per la privacy

Nella configurazione di un microservizio si è tenuti a specificare un link ai documenti o alla pagina contenenti tutte le informazioni sulla privacy degli utenti. Al fine di poter utilizzare i servizi offerti dal microservizio, ogni utente è chiamato ad accettare tali documenti. È quindi del proprietario del microservizio la responsabilità di fornire un documento per la privacy adeguato.

Es. Se all'utente sono richiesti dati personali, è richiesto un documento per la privacy GDPR compliant.

A tale scopo, ogni microservizio deve necessariamente possedere un entrypoint dedicato (specificato nella configurazione) utile a registrare l'accettazione dei documenti sulla privacy da parte di un determinato utente. Questo entrypoint dovrà accettare solo richieste HTTP con metodo PUT, senza payload, ma riportanti un identity token valido.

Dati ricevibili

Come è possibile vedere nello schema per la configurazione, ogni dato che è possibile richiedere è identificato da una stringa identificativa. Tra questi dati sono presenti alcuni predefiniti oppure è possibile definirne di personali. I dati definiti tramite configurazione sono richiesti all'utente nell'app mobile per mezzo di appositi form.

Attraverso la configurazione è possibile specificare ad ogni entrypoint quali dati l'utente può inviare. Ogni gruppo di dati aggiornato sarà inviato all'entrypoint per mezzo del protocollo HTTP, con una richiesta di tipo PATCH, ogni qualvolta questi sono aggiornati. I dati aggiornati saranno contenuti nel payload della richiesta e identificati per mezzo della loro stringa identificativa. Di seguito un esempio di payload in formato JSON.

{
  "telephone": "123456789",
  "email": "[email protected]",
  "extraServices": ["a", "b", "c"]
}

Se allo stesso entrypoint viene invece inviata una richiesta GET, allora il microservizio ha l'obbligo di rispondere mostrando tutti i dati aggiornati dell'utente collegati a quell'entrypoint. La risposta deve essere in formato JSON e deve rispettare la sintassi illustrata nel precedente esempio.