sparky library
@author viniciusddrft Support for doing something awesome. More dartdocs go here.
Classes
- AuthJwt
- CorsConfig
- Configuration for Cross-Origin Resource Sharing (CORS).
- CronExpression
-
Standard 5-field cron expression parser:
minute hour day-of-month month day-of-week. - CsrfConfig
- Synchronized-token CSRF protection (double-submit cookie pattern).
- HealthCheckConfig
-
Configuration for the built-in
/health(liveness) and/ready(readiness) endpoints. - HealthCheckResult
- Result returned by a HealthCheck function.
- MetricsConfig
- Enables a Prometheus text exposition endpoint and HTTP request metrics.
- MultipartData
- The result of parsing a multipart/form-data request body.
- MultipartParser
- Helper to parse multipart data from a stream of bytes.
- OpenApiConfig
- Enables OpenAPI 3.0 JSON and Swagger UI routes on the server.
- OpenApiInfo
- Metadata for the top-level OpenAPI info object.
- OpenApiOperation
- Optional documentation attached to an HTTP Route.
- OpenApiServer
-
A single entry in
servers(OpenAPI 3.0). - Pipeline
- A class representing a pipeline of middleware functions.
- PrometheusMetrics
- In-process Prometheus text format 0.0.4 metrics for Sparky.
- RateLimiter
- Configuration for rate limiting requests.
- Response
- This class handles responses, with some constructors already configured with request code.
- Route
- Base class of a route in Sparky; HTTP routes and WebSocket routes extend directly from it.
- RouteGroup
- Groups multiple routes under a common path prefix.
- RouteHttp
-
HTTP route class, already equipped with constructors to handle
Get,Post,Put,DeletePatch,Head,Options,Tracebut it's possible to customize and make your route work with more than one method. - RouteWebSocket
- WebSocket route class
- ScheduledTask
- A single job scheduled either by cron expression or fixed interval.
- Scheduler
- Runtime handle for SchedulerConfig. Internal — managed by Sparky.
- SchedulerConfig
-
Scheduler configuration passed to
Sparky.single(scheduler: ...). - SecurityHeadersConfig
- Configuration for security headers middleware (Helmet-style).
- Sparky
- Main logic file of Sparky's operation.
- SparkyBase
- SparkyCluster
- Represents a cluster of Sparky server instances running across isolates.
- SseEvent
- Represents a single Server-Sent Event.
- StaticFiles
- Middleware that serves static files from a directory.
- UploadedFile
- Represents an uploaded file from a multipart/form-data request.
- Validator
- Validates a Map<String, dynamic> against a set of rules per field.
Enums
- AcceptedMethods
- Enum with web request methods.
- HealthStatus
- Health status reported by a single check or the overall endpoint.
- LogConfig
- Enum with log configuration.
- LogType
- Enum with log types.
Mixins
- Logs
- A mixin that provides logging functionalities for the Sparky server.
Extensions
Functions
-
aggregateHealthStatus(
Iterable< HealthStatus> statuses) → HealthStatus - Worst-case aggregation: any DOWN → DOWN; else any DEGRADED → DEGRADED; else UP.
-
buildOpenApiDocument(
{required List< Route> routes, required OpenApiInfo info, List<OpenApiServer> ? servers}) → Map<String, Object?> -
Builds an OpenAPI 3.0.3 document map from HTTP
routes. -
buildSwaggerUiHtml(
{required String specUrl, required String cdnBase}) → String -
Builds a minimal Swagger UI page that loads the spec from
specUrl(usually relative). -
custom(
bool predicate(Object? value), String message) → ValidationRule - Custom validation with a user-provided predicate.
-
extractBoundary(
String? contentTypeHeader) → String? - Extracts the boundary string from a Content-Type header value.
-
isBool(
String field, Object? value) → String? - The value must be a bool.
-
isDouble(
String field, Object? value) → String? - The value must be a double.
-
isEmail(
String field, Object? value) → String? - The string value must be a valid email address.
-
isInt(
String field, Object? value) → String? - The value must be an int.
-
isList(
String field, Object? value) → String? - The value must be a List.
-
isMap(
String field, Object? value) → String? - The value must be a Map.
-
isNum(
String field, Object? value) → String? - The value must be a num (int or double).
-
isRequired(
String field, Object? value) → String? - The field must be present and non-null.
-
isString(
String field, Object? value) → String? - The value must be a String.
-
jsonStringEscape(
String s) → String -
Escapes
sfor use inside a single-quoted JavaScript string literal. -
matches(
RegExp regex, {String? message}) → ValidationRule -
The string must match the given
regex. -
max(
num maximum) → ValidationRule -
The numeric value must be <=
maximum. -
maxItems(
int length) → ValidationRule -
The list must have at most
lengthelements. -
maxLength(
int length) → ValidationRule -
The string must have at most
lengthcharacters. -
mergeOpenApiRoutes(
List< Route> routes, OpenApiConfig? openApi) → List<Route> -
If
openApiis null or OpenApiConfig.enabled is false, returnsroutesunchanged. -
min(
num minimum) → ValidationRule -
The numeric value must be >=
minimum. -
minItems(
int length) → ValidationRule -
The list must have at least
lengthelements. -
minLength(
int length) → ValidationRule -
The string must have at least
lengthcharacters. -
oneOf(
List< Object> values) → ValidationRule -
The value must be one of the allowed
values. -
sparkyPathToOpenApi(
String sparkyPath) → String -
Converts a Sparky path (
/users/:id) to an OpenAPI path (/users/{id}).
Typedefs
-
HealthCheck
= FutureOr<
HealthCheckResult> Function() - A single health probe.
-
Middleware
= Future<
Response> Function(HttpRequest request) - In this file, there are all types used in Sparky. Normal middleware that receives an HttpRequest and returns a Future<Response>.
-
MiddlewareNullable
= Future<
Response?> Function(HttpRequest request) - Nullable middleware that receives an HttpRequest and returns a Future<Response?>.
-
MiddlewareWebSocket
= Future<
void> Function(WebSocket webSocket) - WebSocket middleware that receives a WebSocket and returns void.
-
ScheduledJob
= FutureOr<
void> Function() - Callback executed by a ScheduledTask.
-
SparkyFactory
= FutureOr<
Sparky> Function(int isolateIndex) - Factory function for creating a Sparky server instance inside an isolate.
- ValidationRule = String? Function(String field, Object? value)
-
A validation rule receives the field name, its value (nullable),
and returns an error message or
nullif valid.
Exceptions / Errors
- BadGateway
- 502 Bad Gateway
- BadRequest
- 400 Bad Request
- BodyTooLargeException
- Conflict
- 409 Conflict
- ErrorRouteEmpty
- Error thrown when Sparky is initialized with an empty set of routes.
- Forbidden
- 403 Forbidden
- HttpException
- Base class for HTTP exceptions that auto-map to status codes.
- InternalServerError
- 500 Internal Server Error
- MethodNotAllowed
- 405 Method Not Allowed
- NotFound
- 404 Not Found
- RoutesRepeated
- Error thrown when duplicate route names are detected during Sparky initialization.
- 503 Service Unavailable
- SparkyError
- Base class for all internal Sparky errors.
- TooManyRequests
- 429 Too Many Requests
- 401 Unauthorized
- UnprocessableEntity
- 422 Unprocessable Entity