Protocol Proxy: Specifiche Implementative

Requisiti Generali - controllare pagina standard e convenzioni

• Ogni microservizio deve rispettare gli standard della piattaforma

• Ogni proxy deve soddisfare i requisiti suggeriti dal 12 factors manifest

• Esposizione di un endpoint/status per l'healthcheck: esso deve essere restituire 200 se il sistema è "healthy" e 503 in caso si presentino un problemi di connessione con kafka

• Esposizione delle metriche mediante l'endpoint /metrics con Prometheus utilizzando la convenzione da loro suggerita

• Terminazione pulita del servizio (timeout di 15 secondi)

• Esposizione di un endpoint /docs per la consultazione della documentazione delle API esposte dal servizio secondo lo standard OpenAPI

• Integrazione con Sentry per l'error reporting

• Il sistema di logging deve rispettare il formato Apache e descrivere nei tre livelli debug, error e info. Ogni log, quando possibile, deve loggare il remote_id e l'id del documento processato

• Il README deve seguire le linee guida della pubblicazione del software open source

• il nome del progetto e del servizio devono essere nella seguente forma : "Protocol Proxy <Nome del Protocollo Specifico>"

• Inserire il file .gitlab-ci.yml riportando in esso questa pipeline

Metriche in dettaglio

Il Protocol Proxy deve esporre le seguenti metriche:

Metrica	Labels	Descrizione
oc_document_validation_errors_total	cluster, env, app_name	la metrica deve misurare gli errori di validazione sull'evento letto (es. il transmission_type contiene un valore diverso da Inbound o Outbound)
oc_api_requests_total	cluster, env, method, app_name, status_code	la metrica deve monitorare le chiamate http indicandone lo status code
oc_document_success_events_total	cluster, env, app_name	la metrica deve misurare solo gli eventi per cui il proxy ha una configurazione e che sono stati processati con successo
oc_document_failed_events_total	cluster, env, app_name	la metrica deve misurare gli eventi validi di cui però è fallito il processing per qualsiasi motivo (escluso il caso in cui non esiste una configurazione per esso)
oc_document_provider_errors_total	cluster, env, app_name	la metrica deve misurare gli eventi validi di cui però è fallito il processing a causa di un errore sul provider
oc_document_internal_errors_total	cluster, env, app_name	la metrica deve misurare gli eventi validi di cui però è fallito il processing per errori interni al codice
oc_document_provider_latency_bucket	cluster, env, app_name	istogramma che mostra la distribuzione di latenza delle risposte del provider

Requisiti normativi

• Avere una specifica in formato OpenAPI v3

• Rispettare la Linee Guida di interoperabilità: in particolare per quanto riguarda

  • il formato dei dati (4.2)

  • raccomandazioni sul naming (4.3) optando per la scelta di snake_case per i nomi degli attributi

  • logging (4.4)

  • risultare valido nel validatore ufficiale OA3

Documentazione API di Esempio - Swagger

Metrics

Metriche Prometheus

GEThttps://api.qa.stanzadelcittadino.it/registry-proxy/agspr/v1/metrics

Response

200422

Successful Response

Body

text/plain

string

Request

JavaScriptCurlPython

const response = await fetch('https://api.qa.stanzadelcittadino.it/registry-proxy/agspr/v1/metrics', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200422

text

Get Health Kafka Status

Get Service Status

GEThttps://api.qa.stanzadelcittadino.it/registry-proxy/agspr/v1/status

Response

200422503

Successful Response

Body

application/problem+json

status*Status

Request

JavaScriptCurlPython

const response = await fetch('https://api.qa.stanzadelcittadino.it/registry-proxy/agspr/v1/status', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200422503

{
  "status": "text"
}

Get Schema

Get local Schema

GEThttps://api.qa.stanzadelcittadino.it/registry-proxy/agspr/v1/schema

Response

200422

Successful Response

Body

application/json

any

Request

JavaScriptCurlPython

const response = await fetch('https://api.qa.stanzadelcittadino.it/registry-proxy/agspr/v1/schema', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

422

{
  "type": "text",
  "title": "text",
  "detail": "text",
  "instance": "text"
}

Save Tenant

Create New Tenant Configuration

POSThttps://api.qa.stanzadelcittadino.it/registry-proxy/agspr/v1/tenants/

Body

application/json

aoo_code*Aoo Code

base_url*Base Url

created_atCreated At

description*Description

institution_code*Institution Code

modified_atModified At

slug*Slug

id*Id

Response

201422

Successful Response

Body

application/json

any

Request

JavaScriptCurlPython

const response = await fetch('https://api.qa.stanzadelcittadino.it/registry-proxy/agspr/v1/tenants/', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "aoo_code": "text",
      "base_url": "text",
      "description": "text",
      "institution_code": "text",
      "slug": "text",
      "id": "text"
    }),
});
const data = await response.json();

Response

422

{
  "type": "text",
  "title": "text",
  "detail": "text",
  "instance": "text"
}

Get Tenant

Get Tenant Form Schema

GEThttps://api.qa.stanzadelcittadino.it/registry-proxy/agspr/v1/tenants/{id}

Path parameters

id*Id

Response

200422

Successful Response

Body

application/json

any

Request

JavaScriptCurlPython

const response = await fetch('https://api.qa.stanzadelcittadino.it/registry-proxy/agspr/v1/tenants/{id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

422

{
  "type": "text",
  "title": "text",
  "detail": "text",
  "instance": "text"
}

Update Tenant

Edit Existing Tenant Configuration

PUThttps://api.qa.stanzadelcittadino.it/registry-proxy/agspr/v1/tenants/{id}

Path parameters

id*Id

Body

application/json

aoo_code*Aoo Code

base_url*Base Url

created_atCreated At

description*Description

institution_code*Institution Code

modified_atModified At

slug*Slug

Response

200422

Successful Response

Body

application/json

any

Request

JavaScriptCurlPython

const response = await fetch('https://api.qa.stanzadelcittadino.it/registry-proxy/agspr/v1/tenants/{id}', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "aoo_code": "text",
      "base_url": "text",
      "description": "text",
      "institution_code": "text",
      "slug": "text"
    }),
});
const data = await response.json();

Response

422

{
  "type": "text",
  "title": "text",
  "detail": "text",
  "instance": "text"
}

Delete Tenant

Disable Tenant Configuration

DELETEhttps://api.qa.stanzadelcittadino.it/registry-proxy/agspr/v1/tenants/{id}

Path parameters

id*Id

Response

204422

Successful Response

Request

JavaScriptCurlPython

const response = await fetch('https://api.qa.stanzadelcittadino.it/registry-proxy/agspr/v1/tenants/{id}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Response

422

{
  "type": "text",
  "title": "text",
  "detail": "text",
  "instance": "text"
}

Save Service

Create New Service Configuration

POSThttps://api.qa.stanzadelcittadino.it/registry-proxy/agspr/v1/services/

Body

application/json

is_active*Is Active

ws_url_fascicolo*Ws Url Fascicolo

ws_url_protocol*Ws Url Protocol

username*Username

password*Password

codente*Codente

codice_amministrazione*Codice Amministrazione

email*Email

class_cod*Class Cod

denominazione*Denominazione

id_unit_org*Id Unit Org

codice_aoo*Codice Aoo

dispatch_type*Dispatch Type

tipo_documentoTipo Documento

folder_yearFolder Year

folder_numberFolder Number

competence_unitCompetence Unit

creation_unitCreation Unit

id*Id

tenant_id*Tenant Id

Response

201422

Successful Response

Body

application/json

any

Request

JavaScriptCurlPython

const response = await fetch('https://api.qa.stanzadelcittadino.it/registry-proxy/agspr/v1/services/', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "is_active": false,
      "ws_url_fascicolo": "text",
      "ws_url_protocol": "text",
      "username": "text",
      "password": "text",
      "codente": "text",
      "codice_amministrazione": "text",
      "email": "text",
      "class_cod": "text",
      "denominazione": "text",
      "id_unit_org": "text",
      "codice_aoo": "text",
      "dispatch_type": "text",
      "id": "text",
      "tenant_id": "text"
    }),
});
const data = await response.json();

Response

422

{
  "type": "text",
  "title": "text",
  "detail": "text",
  "instance": "text"
}

Get Service

Get Service Form Schema

GEThttps://api.qa.stanzadelcittadino.it/registry-proxy/agspr/v1/services/{id}

Path parameters

id*Id

Response

200422

Successful Response

Body

application/json

any

Request

JavaScriptCurlPython

const response = await fetch('https://api.qa.stanzadelcittadino.it/registry-proxy/agspr/v1/services/{id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

422

{
  "type": "text",
  "title": "text",
  "detail": "text",
  "instance": "text"
}

Update Service

Create New Tenant Configuration

PUThttps://api.qa.stanzadelcittadino.it/registry-proxy/agspr/v1/services/{id}

Path parameters

id*Id

Body

application/json

is_active*Is Active

ws_url_fascicolo*Ws Url Fascicolo

ws_url_protocol*Ws Url Protocol

username*Username

password*Password

codente*Codente

codice_amministrazione*Codice Amministrazione

email*Email

class_cod*Class Cod

denominazione*Denominazione

id_unit_org*Id Unit Org

codice_aoo*Codice Aoo

dispatch_type*Dispatch Type

tipo_documentoTipo Documento

folder_yearFolder Year

folder_numberFolder Number

competence_unitCompetence Unit

creation_unitCreation Unit

Response

200422

Successful Response

Body

application/json

any

Request

JavaScriptCurlPython

const response = await fetch('https://api.qa.stanzadelcittadino.it/registry-proxy/agspr/v1/services/{id}', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "is_active": false,
      "ws_url_fascicolo": "text",
      "ws_url_protocol": "text",
      "username": "text",
      "password": "text",
      "codente": "text",
      "codice_amministrazione": "text",
      "email": "text",
      "class_cod": "text",
      "denominazione": "text",
      "id_unit_org": "text",
      "codice_aoo": "text",
      "dispatch_type": "text"
    }),
});
const data = await response.json();

Response

422

{
  "type": "text",
  "title": "text",
  "detail": "text",
  "instance": "text"
}

Delete Service

Disable Service Configuration

DELETEhttps://api.qa.stanzadelcittadino.it/registry-proxy/agspr/v1/services/{id}

Path parameters

id*Id

Response

204422

Successful Response

Request

JavaScriptCurlPython

const response = await fetch('https://api.qa.stanzadelcittadino.it/registry-proxy/agspr/v1/services/{id}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Response

422

{
  "type": "text",
  "title": "text",
  "detail": "text",
  "instance": "text"
}

Specifiche funzionali

• Il servizio deve essere multi tentant e multi servizio: deve quindi essere in grado di gestire le confiugurazioni per più tenant a cui possono essere attribuiti più servizi con il corrente sistema di protocollazione.

• Ogni richiesta sia essa appartenente alla fase 1 o alla fase 2 descritte nella sezione "workflow sistema di protocollazione" devono essere trattate in maniera atomica.

• Lo storage deve essere compatibile con Aws s3, Azure e local file system.

Configurazione del microservizio (variabili d'ambiente)

Il servizio deve essere configurabile attraverso le seguenti variabili d'ambiente.

Se le varibili senza valore di default non vengono settate, il servizio deve notificare la mancata impostazione attraverso un log di livello error e terminare in maniera pulita la propria esecuzione.

Nome	Default	Descrizione
ENVIRONMENT	local	Indica l'ambiente di sviluppo (locale, dev, prod, ecc.) utilizzato da Sentry.
DEBUG	true	...
SENTRY_ENABLED	false	...
SENTRY_DSN	nessun valore	Endpoint per il monitoraggio di Sentry.
KAFKA_SERVER	kafka:9092	Lista di lunghezza variabile i cui elementi devono essere separati da virgola. lista degli Indirizzi dei broker Kafka per connettersi al cluster.
KAFKA_CONSUMER_GROUP	<nome_del_servizio>	Consumer group per Kafka.
KAFKA_CONSUMER_TOPIC	documents	Identifica il topic da cui consumare gli eventi Kafka.
KAFKA_PRODUCER_TOPIC	documents	Identifica il topic a cui inviare gli eventi Kafka.
KAFKA_RETRY_TOPIC	nessun valore	topic in cui produrre gli eventi consumati dal meccanismo di retry
SERVER_ADDRESS_PORT	0.0.0.0:8080	Indica l'indirizzo e la porta utilizzati per l'healthcheck.
CACHE_EXPIRATION	5m	...
CACHE_EVICTION	10m	...
STORAGE_TYPE	local	Tipo di storage dei pagamenti: s3, azure, local
STORAGE_ENDPOINT	nessun valore	Indirizzo di accesso allo storage.
STORAGE_ACCESS_S3_KEY	nessun valore	Chiave di accesso allo storage.
STORAGE_KEY_S3_ACCESS_SECRET	nessun valore	Chiave segreta di accesso allo storage.
STORAGE_S3_REGION	nessun valore	Location del cloud storage
STORAGE_BUCKET	nessun valore	Nome dello storage
STORAGE_BASE_PATH	"/data/"	Basepath dello storage
STORAGE_AZURE_ACCOUNT	nessun valore	Chiave dello storage AZURE
STORAGE_AZURE_KEY	nessun valore	Password dello storage AZURE
STORAGE_LOCAL_PATH	/data/
SDC_AUTH_TOKEN_USER	nessun valore	utente autenticazione per recuperare il token dalla piattaforma
SDC_AUTH_TOKEN_PASSWORD	nessun valore	password autenticazione per recuperare il token dalla piattaforma

Test

Protocol Proxy Tests Checklist

Se si sta facendo il deploy di un nuovo microservizio per la prima volta o si sta aggiungendo una nuova API o una nuova pagina a una interfaccia esistente, è necessario aggiungere alcuni controlli di qualità minima prima del rilascio.

Controlli

• Test automatici delle API nella CI (usare hurl, qui un esempio di utilizzo e qui un esempio di integrazione nelle CI)

• Test flusso standard

  • Inserire la configurazione del tenant

  • Inserire la configurazione del servizio

  • Inserire un esempio di documento non protocollato nel topic documents e verificare che venga correttamente protocollato

  • Inserire un esempio di documento protocollato nel topic documents e verificare che venga ignorato

  • Inserire un esempio di documento non protocollato nel topic documents per cui non esiste una configurazione di tenant e/o di servizio e verificare che venga ignorato

• Test flusso di errore

  • Modificare la configurazione del servizio in modo che sia errata (mettendo ad esempio credenziali errate)

  • Inserire un esempio di documento non protocollato nel topic documents e verificare che, a seguito del fallimento, venga prodotto un evento nel topic di retry

  • Correggere la configurazione del servizio

  • Inserire il documento prodotto nel topic di retry all'interno del topic documents e verificare che venga correttamente protocollato