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

Documentazione API di Esempio - Swagger

Metrics

get

Metriche Prometheus

Responses
200
Successful Response
text/plain
Responsestring
get
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
get
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
Responseany
get
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
aoo_codestringRequired
base_urlstringRequired
created_atstringOptionalDefault: ""
descriptionstringRequired
institution_codestringRequired
modified_atstringOptionalDefault: ""
slugstringRequired
idstringRequired
Responses
201
Successful Response
application/json
Responseany
post
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
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_documentoany ofOptionalDefault: ""
stringOptional
or
nullOptional
folder_yearany ofOptionalDefault: ""
stringOptional
or
nullOptional
folder_numberany ofOptionalDefault: ""
stringOptional
or
nullOptional
competence_unitany ofOptionalDefault: ""
stringOptional
or
nullOptional
creation_unitany ofOptionalDefault: ""
stringOptional
or
nullOptional
idstringRequired
tenant_idstringRequired
Responses
201
Successful Response
application/json
Responseany
post
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

PreviousConfigurazione tenant e serviziNextProcesso di sviluppo

Last updated

Was this helpful?