Tutto quello che fa sgcREST, mappato sul server REST e i suoi companion, il motore del server OpenAPI e la famiglia del client OpenAPI. Ogni funzionalità si comporta allo stesso modo in Delphi e in C++ Builder, e ogni licenza include il codice sorgente completo. Le sottopagine dei componenti non sono ancora pubblicate per questo lancio, ogni voce qui sotto è autonoma su questa pagina.
CORS, statistiche, tenancy e utenti
Spec-first e code-first
Consuma qualsiasi API descritta con OpenAPI
Da Delphi 7 a 13, C++ Builder
sgcREST è autosufficiente. Viene distribuito con il runtime sgcWebSockets Core incluso, quindi non è un componente aggiuntivo, e gira sulla libreria Indy standard inclusa in RAD Studio.
L'OpenAPI code-first richiede Delphi XE7 o successivo. Generare uno spec da una classe Delphi con attributi si basa sulla RTTI introdotta in XE7. Il server REST, i suoi companion e il motore OpenAPI spec-first girano su Delphi da 7 a 13.
Quattro componenti sulla pagina della palette SGC REST, e tre classi solo-codice per il server e il client OpenAPI, dichiarate nelle unità sgcHTTP_REST_Server* e sgcHTTP_OpenAPI_*.
| Componente | Classe | Palette? | Descrizione |
|---|---|---|---|
| Server REST | TsgcHTTPRESTServer | Sì | Server API REST costruito su TsgcHTTPServer, con gestione CORS e companion agganciabili di statistiche/tenancy. |
| Statistiche del server REST | TsgcHTTPServerStats | Sì | Contatori delle richieste, tracciamento della latenza, /metrics in formato Prometheus e /health in JSON. |
| Tenancy del server REST | TsgcHTTPServer_Tenancy | Sì | Risoluzione multi-tenant per host, path, header o claim JWT. |
| Utenti del server REST | TsgcHTTPServer_Users | Sì | Archivio account locale: aggiungi, valida, esegui l'hashing, assegna ruoli e persisti gli utenti. |
| Server OpenAPI, spec-first | TsgcOpenAPIServerHandler | No, solo-codice | Serve un'API da un documento OpenAPI 3.0/3.1 caricato, con validazione delle richieste. |
| Server OpenAPI, code-first | TsgcOpenAPICodeFirstScanner | No, solo-codice | Genera lo spec OpenAPI da una classe Delphi con attributi RTTI. Richiede Delphi XE7+. |
| Client OpenAPI | TsgcOpenAPI_Client | No, solo-codice | Client runtime generico per qualsiasi endpoint descritto con OpenAPI. |
TsgcHTTPRESTServer è un discendente di TsgcHTTPServer, quindi parte dagli stessi binding e dalla stessa gestione TLS condivisi da ogni server sgc HTTP, e vi sovrappone le aggiunte tipiche di un'API REST.
| Funzionalità | API | Note |
|---|---|---|
| CORS | CORSOptions (Enabled, AllowOrigins, AllowHeaders, AllowMethods) | Disattivo per default. Le richieste preflight OPTIONS vengono risolte automaticamente una volta attivato. |
| Companion delle statistiche | ServerStats: TsgcHTTPServerStats | Aggancia un componente di statistiche e ogni richiesta viene contata e cronometrata senza toccare i route handler. |
| Companion di tenancy | Tenancy: TsgcHTTPServer_Tenancy, Tenant | Aggancia un componente di tenancy per risolvere il tenant del chiamante; Tenant legge il risultato per la richiesta corrente. |
| Contatori delle richieste | TotalRequests, Status1xx fino a Status5xx | Su TsgcHTTPServerStats. Contati per classe di stato man mano che le risposte vengono inviate. |
| Latenza | LatencyMinMs, LatencyAvgMs, LatencyMaxMs | Tracciata per richiesta su TsgcHTTPServerStats, azzerata con Reset. |
| Endpoint delle metriche | GetMetricsText, IsMetricsRequest | Formato di esposizione testuale Prometheus 0.0.4, servito su /metrics. |
| Endpoint di salute | GetHealthJSON, IsHealthRequest | Payload JSON di salute servito su /health, include UptimeSeconds e ActiveConnections. |
| Statistiche per endpoint | GetEndpointStats, Endpoints | Una coppia path/conteggio per endpoint, per un report o una console di amministrazione. |
| Risoluzione del tenant | Resolution, ResolveTenant | Su TsgcHTTPServer_Tenancy. Risolve tramite suffisso host, segmento del path, header o claim JWT. |
| Sorgenti del tenant | HostSuffix, PathSegmentIndex, HeaderName, ClaimName, DefaultTenant | La sorgente letta per la modalità Resolution configurata, e il fallback quando non produce nulla. |
| Risoluzione personalizzata | OnResolveTenant | Sovrascrivi o estendi la logica di risoluzione integrata. |
| Account utente | AddUser, DeleteUser, FindUser, ValidateCredentials, SetPassword, EnableUser, UserExists | Su TsgcHTTPServer_Users. Credenziali salate e con hashing, mai restituite in chiaro. |
| Ruoli | AddRole, RemoveRole, UserHasRole, GetUserRoles | Tag di ruolo liberi per account, verificati da un route handler. |
| Enumerazione | Count, GetUserCount, GetUserByIndex, GetUsernames | Viste in sola lettura per un report o una console di amministrazione; hash della password e salt non sono mai inclusi. |
| Persistenza | LoadUsers, SaveUsers, SaveToFile, LoadFromFile, ExportUsers, ImportUsers | Storage.EncryptAtRest cifra l'archivio; OnLoadUsers/OnSaveUsers sostituiscono un backend personalizzato. |
| Eventi | OnStats, OnResolveTenant, OnValidateCredentials, OnFindUser, OnException | Un evento per companion per i casi non coperti dalla logica integrata. |
Entrambi gli approcci alimentano la stessa tabella delle route e lo stesso contesto di richiesta; cambia solo la sorgente del documento OpenAPI.
| Funzionalità | API | Note |
|---|---|---|
| Tabella delle route | TsgcOpenAPIRouteTable (Add, Match) | Costruita dalla sezione paths di uno spec; abbina un verbo e un path a un operationId. |
| Contesto di richiesta | TsgcOpenAPIServerContext (Request, Response, PathParams, QueryParams) | Un'istanza per richiesta abbinata, liberata quando la richiesta termina. |
| Parametri tipizzati | PathParamAsString, PathParamAsInteger, QueryParamAsString, QueryParamAsInteger, QueryParamAsBoolean | Legge e converte un valore di path o query in un'unica chiamata. |
| Accesso al body | BodyAsString, BodyAsJSON, HeaderValue | Analizza il body della richiesta una sola volta e mette in cache il risultato. |
| Risposta | RespondJSON, RespondError | Scrive un body JSON con un codice di stato, o un payload di errore strutturato. |
| Ciclo di vita della richiesta | BeforeHandle, AfterHandle, HandleException | Su TsgcOpenAPIServerHandler. Sovrascrivi per aggiungere logging, controlli di autenticazione o mappatura personalizzata degli errori. |
| Validazione | TsgcOpenAPIJSONValidator | Verifica body, parametri query e path rispetto agli JSON Schema dichiarati dallo spec. |
| Generazione dello spec | GenerateSpec, Title, Description, Version, BasePath | Su TsgcOpenAPICodeFirstScanner. Produce un documento OpenAPI 3.0 dalla RTTI di una classe con attributi. |
| Attributi del contratto | sgcServiceContract, sgcRoute, sgcSummary, sgcDescription, sgcTag, sgcResponse | Attributi a livello di classe e di metodo che popolano lo spec generato. |
| Attributi dei verbi | sgcHttpGet, sgcHttpPost, sgcHttpPut, sgcHttpDelete, sgcHttpPatch, sgcHttpHead, sgcHttpOptions | Dichiara il verbo HTTP a cui risponde un metodo annotato. |
| Binding dei parametri | sgcFromPath, sgcFromQuery, sgcFromHeader, sgcFromBody, sgcRequired | Dichiara da dove viene letto ogni parametro del metodo. |
| Dispatch | TsgcOpenAPICodeFirstDispatcher (RegisterController, DispatchOperation, IsRegistered) | Invoca direttamente il metodo annotato registrato per un operationId, senza catene if manuali. |
| Dipendenza | Delphi XE7 o successivo | Lo scanning e il dispatch code-first si basano su System.Rtti, non disponibile prima di XE7. Lo spec-first non ha questo requisito. |
Un client generico per qualsiasi endpoint descritto con OpenAPI, con Basic auth, bearer token, OAuth2 e JWT generici integrati.
| Funzionalità | API | Note |
|---|---|---|
| Chiamata base | HTTP_REQUEST | Su TsgcOpenAPI_Client. Porta una coppia TsgcOpenAPIRequest/TsgcOpenAPIResponse verso qualsiasi endpoint. |
| URL base | SetBaseURL, GetBaseURL | L'endpoint rispetto a cui si risolve ogni path relativo di una richiesta. |
| Autenticazione generica | Authentication (Basic, Token, OAuth2, JWT) | Basic auth e bearer token, più i flussi OAuth2 e JWT generici. |
| Trasporto | TLSOptions, ProxyOptions, EncodeBodyAsUTF8 | Configurazione TLS e proxy standard condivisa con il resto dello stack sgc HTTP. |
| Avanzamento e log | OnUpload, OnDownload, Log, LogFileName | Traccia i body di richiesta/risposta di grandi dimensioni e opzionalmente registra ogni chiamata su file. |
| Hook di richiesta | OnBeforeRequest | Ispeziona o modifica una richiesta prima che venga inviata. |
| Hook TLS | OnSSLVerifyPeer, OnSSLGetHandler, OnSSLAfterCreateHandler | Verifica del certificato e personalizzazione dell'handler, condivisi con il resto dello stack sgc HTTP. |
Standard pubblici sul filo, e lo stesso sorgente su ogni compilatore supportato.
| Ambito | Dettaglio |
|---|---|
| OpenAPI | OpenAPI 3.0 e 3.1, sia per l'instradamento spec-first del server sia per gli JSON Schema con cui la validazione delle richieste confronta. |
| Autenticazione client | Autenticazione HTTP Basic e bearer token, più OAuth2 e JWT generici. |
| Metriche | Formato di esposizione testuale Prometheus 0.0.4 su /metrics. |
| Piattaforme | Windows Win32, Windows Win64, Linux64, macOS, iOS e Android per tutte e sette le classi. |
| Dipendenza | Nessuna oltre al runtime sgcWebSockets Core incluso. Nessun componente aggiuntivo per nessuna delle sette classi. |
| Compilatori | Delphi e C++ Builder dalla versione 7 alla 13. L'OpenAPI code-first richiede Delphi XE7 o successivo. |
| Edizioni | La famiglia del server REST viene distribuita anche dentro sgcWebSockets a partire dalla Professional, il server OpenAPI a partire dalla Enterprise, e la famiglia del client OpenAPI a partire dalla Standard. |
| Licenze | Autonomo. Il runtime sgcWebSockets Core è incluso e il codice sorgente completo fa parte della fornitura. |