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

get

Metriche Prometheus

Responses

200

Successful Response

text/plain

stringOptional

422

Validation Error

application/problem+json

get/metrics

HTTPcURLJavaScriptPython

GET /registry-proxy/agspr/v1/metrics HTTP/1.1
Host: api.qa.stanzadelcittadino.it
Accept: */*

text

Get Health Kafka Status

get

Get Status

Responses

200

Successful Response

application/problem+json

typestringRequired

titlestringRequired

statusinteger · int32 · nullableRequired

detailany ofRequired

stringOptional

or

instancestring · nullableRequired

422

Validation Error

application/problem+json

503

Service Unavailable

application/problem+json

get/status

HTTPcURLJavaScriptPython

GET /registry-proxy/agspr/v1/status HTTP/1.1
Host: api.qa.stanzadelcittadino.it
Accept: */*

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

Get Schema

get

Get local Schema

Responses

200

Successful Response

application/json

anyOptional

422

Validation Error

application/problem+json

get/schema

HTTPcURLJavaScriptPython

GET /registry-proxy/agspr/v1/schema HTTP/1.1
Host: api.qa.stanzadelcittadino.it
Accept: */*

No content

Save Tenant Configuration

post

Create New Tenant Configuration

Body

application/json

aoo_codestringRequired

base_urlstringRequired

created_atstringOptionalDefault: ""

descriptionstringRequired

institution_codestringRequired

modified_atstringOptionalDefault: ""

slugstringRequired

idstringRequired

Responses

201

Successful Response

application/json

anyOptional

422

Validation Error

application/problem+json

post/tenants/

HTTPcURLJavaScriptPython

POST /registry-proxy/agspr/v1/tenants/ HTTP/1.1
Host: api.qa.stanzadelcittadino.it
Content-Type: application/json
Accept: */*
Content-Length: 143

{
  "aoo_code": "text",
  "base_url": "text",
  "created_at": "",
  "description": "text",
  "institution_code": "text",
  "modified_at": "",
  "slug": "text",
  "id": "text"
}

No content

Save Service Configuration

post

Save Service Configuration

Body

application/json

is_activebooleanRequired

ws_url_fascicolostringRequired

ws_url_protocolstringRequired

usernamestringRequired

passwordstringRequired

codentestringRequired

codice_amministrazionestringRequired

emailstringRequired

class_codstringRequired

denominazionestringRequired

id_unit_orgstringRequired

codice_aoostringRequired

dispatch_typestringRequired

tipo_documentostring · nullableOptionalDefault: ""

folder_yearstring · nullableOptionalDefault: ""

folder_numberstring · nullableOptionalDefault: ""

competence_unitstring · nullableOptionalDefault: ""

creation_unitstring · nullableOptionalDefault: ""

idstringRequired

tenant_idstringRequired

Responses

201

Successful Response

application/json

anyOptional

422

Validation Error

application/problem+json

post/services/

HTTPcURLJavaScriptPython

POST /registry-proxy/agspr/v1/services/ HTTP/1.1
Host: api.qa.stanzadelcittadino.it
Content-Type: application/json
Accept: */*
Content-Length: 402

{
  "is_active": true,
  "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",
  "tipo_documento": "",
  "folder_year": "",
  "folder_number": "",
  "competence_unit": "",
  "creation_unit": "",
  "id": "text",
  "tenant_id": "text"
}

No content

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