GitHub Workflow Status (build main)

Estado en Maven Central

Tabla de estado (con badge por modulo)

Modulo	GroupId	ArtifactId	Desplegado
ether-parent	dev.rafex.ether.parent	ether-parent	si
ether-config	dev.rafex.ether.config	ether-config	si
ether-crypto	dev.rafex.ether.crypto	ether-crypto	si
ether-database-core	dev.rafex.ether.database	ether-database-core	si
ether-jdbc	dev.rafex.ether.jdbc	ether-jdbc	si
ether-database-postgres	dev.rafex.ether.database	ether-database-postgres	si
ether-database-sqlite	dev.rafex.ether.database	ether-database-sqlite	si
ether-json	dev.rafex.ether.json	ether-json	si
ether-cron	dev.rafex.ether.cron	ether-cron	si
ether-jwt	dev.rafex.ether.jwt	ether-jwt	si
ether-observability-core	dev.rafex.ether.observability	ether-observability-core	si
ether-http-core	dev.rafex.ether.http	ether-http-core	si
ether-http-security	dev.rafex.ether.http	ether-http-security	si
ether-http-problem	dev.rafex.ether.http	ether-http-problem	si
ether-http-openapi	dev.rafex.ether.http	ether-http-openapi	si
ether-http-client	dev.rafex.ether.http	ether-http-client	si
ether-logging-core	dev.rafex.ether.logging	ether-logging-core	si
ether-ai-core	dev.rafex.ether.ai	ether-ai-core	si
ether-ai-openai	dev.rafex.ether.ai	ether-ai-openai	si
ether-ai-deepseek	dev.rafex.ether.ai	ether-ai-deepseek	si
ether-websocket-core	dev.rafex.ether.websocket	ether-websocket-core	si
ether-http-jetty12	dev.rafex.ether.http	ether-http-jetty12	si
ether-websocket-jetty12	dev.rafex.ether.websocket	ether-websocket-jetty12	si
ether-websocket-proxy-jetty12	dev.rafex.ether.websocket	ether-websocket-proxy-jetty12	si
ether-webhook	dev.rafex.ether.webhook	ether-webhook	si
ether-glowroot-jetty12	dev.rafex.ether.glowroot	ether-glowroot-jetty12	si
ether-archetype	dev.rafex.ether	ether-hexagonal-archetype	si
ether-brain	dev.rafex.ether.brain	ether-brain-parent	si
ether-di	dev.rafex.ether.di	ether-di	si

JSON de estado

Consulta el archivo docs/maven-central-status.json.

¿Qué es Ether?

Ether es un ecosistema de bibliotecas Java modulares para construir microservicios y APIs sin frameworks pesados. Cada módulo es independiente, tiene cero magia, y puede adoptarse de forma incremental.

Sin Spring. Sin Quarkus. Sin Micronaut.

Solo Java 21, Jetty 12 y las partes que realmente necesitas.

Principios de diseño

Interfaces primero — cada capa expone contratos, no implementaciones
Cero magia — sin reflexión en tiempo de ejecución, sin anotaciones de framework
Modular — usa solo los módulos que necesitas; sin transitive bloat
Testeable — todas las interfaces son fáciles de mockear; no hay statics ocultos
Java 21 — records, sealed classes, pattern matching, virtual threads

Arquitectura del ecosistema

graph TD
    subgraph Fundación
        P[ether-parent<br/>BOM + POM padre]
        DI[ether-di<br/>Lazy, Closer, Bootstrap]
    end

    subgraph Contratos["Contratos — APIs puras sin implementación"]
        CFG[ether-config<br/>Configuración tipada]
        DBC[ether-database-core<br/>DatabaseClient, RowMapper]
        JSON[ether-json<br/>JsonCodec]
        OBS[ether-observability-core<br/>TimingRecorder, RequestIdGenerator, ProbeCheck]
        HC[ether-http-core<br/>HttpExchange, HttpHandler, Middleware]
        SEC[ether-http-security<br/>CorsPolicy, SecurityHeadersPolicy]
        WSC[ether-websocket-core<br/>WebSocketEndpoint, WebSocketSession]
    end

    subgraph Implementaciones["Implementaciones concretas"]
        JWT[ether-jwt<br/>TokenIssuer, TokenVerifier]
        JDBC[ether-jdbc<br/>JdbcDatabaseClient]
        PG[ether-database-postgres<br/>PostgreSQL helpers]
        PROB[ether-http-problem<br/>RFC 7807 ProblemDetails]
        OAI[ether-http-openapi<br/>OpenAPI 3.1 spec builder]
        CLI[ether-http-client<br/>EtherHttpClient sobre JDK HttpClient]
        HJ[ether-http-jetty12<br/>Servidor HTTP completo con Jetty 12]
        WSJ[ether-websocket-jetty12<br/>WebSocket sobre Jetty 12]
    end

    subgraph Integraciones["Integraciones y utilidades"]
        WH[ether-webhook<br/>Entrega y verificación HMAC]
        GLW[ether-glowroot-jetty12<br/>Instrumentación Glowroot APM]
    end

    P --> CFG & DBC & JSON & OBS & HC & SEC & WSC
    DBC --> JDBC & PG
    JSON --> JWT & PROB & OAI & CLI
    HC --> PROB & HJ
    SEC --> HJ
    OBS --> HJ
    CFG --> HJ
    CLI --> WH
    WSC --> WSJ
    HJ --> GLW
    WSJ --> GLW

Grafo de dependencias de despliegue

El orden importa — cada módulo necesita que sus dependencias estén en Maven Central primero:

graph LR
    P[ether-parent] --> CFG[ether-config]
    P --> DBC[ether-database-core]
    P --> JSON[ether-json]
    P --> OBS[ether-observability-core]
    P --> HC[ether-http-core]
    P --> SEC[ether-http-security]
    P --> WSC[ether-websocket-core]

    DBC --> JDBC[ether-jdbc]
    DBC --> PG[ether-database-postgres]

    JSON --> JWT[ether-jwt]
    JSON --> PROB[ether-http-problem]
    HC --> PROB
    JSON --> OAI[ether-http-openapi]
    JSON --> CLI[ether-http-client]

    CFG --> HJ[ether-http-jetty12]
    JSON --> HJ
    OBS --> HJ
    HC --> HJ
    SEC --> HJ
    PROB --> HJ

    WSC --> WSJ[ether-websocket-jetty12]

    CLI --> WH[ether-webhook]
    JSON --> WH

    HC --> GLW[ether-glowroot-jetty12]
    HJ --> GLW
    WSC --> GLW
    WSJ --> GLW

Módulos

💉 Inyección de dependencias

ether-di

Bloques de construcción para DI explícita en Java 21+: Lazy<T> (inicialización perezosa thread-safe), Closer (cierre LIFO de recursos) y Bootstrap (arranque con warmup y shutdown hook). Sin reflexión, sin anotaciones, compatible con GraalVM native-image.

// Contenedor de dependencias en Java puro
public class AppContainer implements AutoCloseable {
    private final Closer closer = new Closer();
    private final Lazy<DataSource> db = new Lazy<>(() ->
            closer.register(DataSourceFactory.create(config.get())));
    private final Lazy<UserService> service = new Lazy<>(() ->
            new UserServiceImpl(db.get()));
 
    @Override public void close() { closer.close(); }
}
 
// Arranque con warmup y shutdown graceful
Bootstrap.start(AppContainer::new, AppContainer::warmup);

🏗 Fundación

ether-parent

POM padre y BOM del ecosistema. Gestiona versiones de todas las dependencias externas (Jackson, Jetty, Glowroot). Todos los módulos de ether lo usan como padre.

<parent>
  <groupId>dev.rafex.ether.parent</groupId>
  <artifactId>ether-parent</artifactId>
  <version>8.0.0</version>
  <relativePath/>
</parent>

⚙️ Configuración

ether-config

Configuración tipada con fuentes apilables (YAML, JSON, TOML, properties, env vars, system properties) y binding directo a records de Java con validación.

// Define tu config como un record
record ServerConfig(
    @Required String host,
    @Min(1) @Max(65535) int port,
    @NotBlank String databaseUrl
) {}
 
// Carga y valida
var config = EtherConfig.builder()
    .source(new YamlFileConfigSource("config.yaml"))
    .source(new EnvironmentConfigSource())   // env override
    .build()
    .bind("server", ServerConfig.class);

🗄 Acceso a datos

ether-database-core

Contratos JDBC-first: DatabaseClient, RowMapper, TransactionRunner. Sin implementación — define el contrato que usas en tu código.

ether-jdbc

Implementación JDBC de ether-database-core. Sin Spring, sin Hibernate, sin pool externo obligatorio.

var client = new JdbcDatabaseClient(dataSource);
var users = client.query(
    "SELECT * FROM users WHERE active = ?",
    List.of(true),
    rs -> new User(rs.getLong("id"), rs.getString("name"))
);

ether-database-postgres

Clasificador de errores PostgreSQL y constantes de SQL states para manejar unique_violation, foreign_key_violation, etc. de forma limpia.

📦 Serialización

ether-json

Interfaz JsonCodec sobre Jackson. Intercambia la implementación sin tocar tu código.

JsonCodec codec = new JacksonJsonCodec();
 
// Serializar
String json = codec.write(new User(1L, "Alice"));
 
// Deserializar
User user = codec.read(json, User.class);
 
// Tipos genéricos
List<User> users = codec.read(json, new TypeReference<List<User>>() {});

ether-cron

Scheduler embebido y ligero basado en ScheduledExecutorService. Cubre intervalos simples y ejecuciones diarias sin Spring, Quartz ni plataforma de jobs externa.

try (var scheduler = CronSchedulers.singleThread()) {
    scheduler.everySeconds("heartbeat", 30, () -> {
        System.out.println("Ether heartbeat...");
    });
}

🔐 Seguridad

ether-jwt

Emisión y verificación de JWT. Soporta HS256, RS256, ES256.

var config = JwtConfig.builder()
    .algorithm(JwtAlgorithm.HS256)
    .secret("tu-secreto-de-256-bits")
    .issuer("tu-servicio")
    .ttlSeconds(3600)
    .build();
 
TokenIssuer issuer = new DefaultTokenIssuer(config);
TokenVerifier verifier = new DefaultTokenVerifier(config);
 
// Emitir
String token = issuer.issue(TokenSpec.forSubject("user-123")
    .claim("roles", List.of("admin"))
    .build());
 
// Verificar
var result = verifier.verify(token);
if (result.isOk()) {
    String subject = result.claims().subject();
}

🔭 Observabilidad

ether-observability-core

Interfaces puras: RequestIdGenerator, TimingRecorder, ProbeCheck. Tu código depende solo de estas interfaces — el APM concreto se inyecta como implementación.

// Health check que se expone en /health
var aggregator = new ProbeAggregator(List.of(
    ProbeCheck.named("database", () -> db.ping()),
    ProbeCheck.named("cache",    () -> cache.ping())
));
ProbeReport report = aggregator.run(ProbeKind.READINESS);
// report.status() → UP | DOWN | DEGRADED

🌐 HTTP

ether-http-core

Contratos del pipeline HTTP: HttpExchange, HttpHandler, Middleware. Sin Jetty, sin Servlet — puro Java.

// Un handler es una función HttpExchange → HttpExchange
HttpHandler users = exchange -> exchange.json(200, userService.findAll());
 
// Un middleware envuelve handlers
Middleware logging = next -> exchange -> {
    System.out.println(exchange.method() + " " + exchange.path());
    return next.handle(exchange);
};

graph LR
    R[Request] --> M1[Middleware 1\nLogging]
    M1 --> M2[Middleware 2\nAuth]
    M2 --> H[HttpHandler\ntu lógica]
    H --> M2
    M2 --> M1
    M1 --> Res[Response]

ether-http-security

Records inmutables para configurar CORS, security headers, allowlist de IPs y rate limiting.

var profile = HttpSecurityProfile.builder()
    .cors(CorsPolicy.builder()
        .allowOrigin("https://miapp.com")
        .allowMethods("GET", "POST", "PUT", "DELETE")
        .build())
    .securityHeaders(SecurityHeadersPolicy.strict())
    .rateLimit(RateLimitPolicy.of(100, Duration.ofMinutes(1)))
    .build();

ether-http-problem

Respuestas de error RFC 7807 (application/problem+json).

{
  "type": "https://miapi.com/errors/not-found",
  "title": "Resource Not Found",
  "status": 404,
  "detail": "User with id 42 does not exist",
  "instance": "/users/42"
}

ether-http-openapi

Construye especificaciones OpenAPI 3.1 programáticamente y expónlas en /openapi.json.

ether-http-client

Cliente HTTP saliente sobre java.net.http. GET, POST, PUT, DELETE con serialización JSON automática.

ether-http-jetty12 ⭐

El módulo principal para construir servidores HTTP. Integra todos los módulos anteriores en un servidor Jetty 12 listo para producción.

graph TD
    REQ[HTTP Request] --> IP[JettyIpPolicyHandler]
    IP --> RL[JettyRateLimitHandler]
    RL --> CORS[JettyCorsHandler]
    CORS --> SH[JettySecurityHeadersHandler]
    SH --> OBS[JettyObservabilityHandler\nRequest ID + Timing]
    OBS --> AUTH[JettyAuthHandler\nJWT Verification]
    AUTH --> MW[Custom JettyMiddlewares]
    MW --> RES[NonBlockingResourceHandler\ntu HttpHandler]
    RES --> RESP[HTTP Response]

var server = JettyServerFactory.create(
    JettyServerConfig.of(8080),
    routes,
    codec,
    tokenVerifier,
    securityProfile,
    new UuidRequestIdGenerator(),
    sample -> log.info("{} took {}ms", sample.operation(), sample.durationMillis()),
    List.of(glowrootHandler::wrap)
);

🔌 WebSocket

ether-websocket-core

Contratos agnósticos al transporte: WebSocketEndpoint, WebSocketSession.

sequenceDiagram
    participant C as Cliente
    participant S as Servidor
    C->>S: HTTP Upgrade
    S->>S: onOpen(session)
    C->>S: Text Message
    S->>S: onText(session, text)
    S->>C: send(response)
    C->>S: Close
    S->>S: onClose(session, status, reason)

ether-websocket-jetty12

Implementación WebSocket sobre Jetty 12. Se integra en el mismo servidor que ether-http-jetty12.

🔗 Integraciones

ether-webhook

Envío y verificación de webhooks con firma HMAC-SHA256.

sequenceDiagram
    participant S as Sender
    participant R as Receiver
    S->>S: sign(payload, secret)
    S->>R: POST /webhook<br/>X-Webhook-Signature: sha256=...
    R->>R: verify(payload, signature, secret)
    R-->>S: 200 OK

ether-glowroot-jetty12

Instrumentación Glowroot APM para Jetty 12. Registra transacciones, tiempos de respuesta, usuarios autenticados y request IDs sin modificar tu código de negocio.

var glowroot = GlowrootJettyHandler.builder()
    .healthPath("/health")
    .requestIdHeader("X-Request-Id")
    .defaultSlowThreshold(2_000)
    .userExtractor(ctx -> ctx instanceof AuthContext a ? a.subject() : null)
    .build();
 
// Se registra como JettyMiddleware — una sola línea en tu server setup
List.of(glowroot::wrap)

🧠 Agentes IA

ether-brain

Runtime hexagonal para agentes de IA en Java 21. Define puertos (ether-brain-ports), lógica de agente (ether-brain-core), memoria in-process, herramientas locales (filesystem, shell) y transporte CLI. Se monta sobre ether-ai-core para llamadas a LLMs.

// Agente listo para correr desde terminal
Bootstrap.start(BrainContainer::new, BrainContainer::warmup);
// → Agente interactivo vía CLI con memoria y herramientas locales

Objetivo del Repositorio

Este repositorio actúa como un hub orquestador para la publicación y despliegue automáticos de los módulos de Ether en Maven Central.

flowchart LR
    DEV[Developer\npush a main] --> CI[GitHub Actions\nValidate Build]
    CI --> RP[Generate\nRelease Plan]
    RP --> VAL[Validate\nversiones vs Central]
    VAL --> DEPLOY[Deploy módulos\nen orden de dependencia]
    DEPLOY --> MC[Maven Central]
    MC --> MAN[Actualizar\nmanifest.json]

Incluye:

Detección automática de cambios por submódulo (git diff)
Release plan con bump semántico de versiones
Validación de colisiones de versión contra Maven Central
Despliegue en orden estricto de dependencias
Generación de Javadoc, fuentes y firmas GPG
Actualización automática del manifest tras despliegue exitoso

Cómo compilar y publicar

Instalar todo localmente

make install-all

Validar compilación (equivalente a CI)

make validate-main-build

Compilar un módulo puntual con sus dependencias

make compile-ether-http-jetty12

make compile-ether-glowroot-jetty12

Generar release plan

# Detecta cambios automáticamente desde el último commit
make release-plan
 
# Forzar todos los módulos (desde el primer commit del repo)
FIRST=$(git rev-list --max-parents=0 HEAD)
make release-plan BASE_REF=$FIRST

Desplegar en Maven Central via GitHub Actions

# dry-run — genera el plan pero no despliega
make publish-plan-ci
 
# deploy real — todos los módulos con cambios
make publish-ci
 
# deploy forzado — todos los módulos
FIRST=$(git rev-list --max-parents=0 HEAD)
make publish-ci BASE_REF=$FIRST

Release local (sin GitHub Actions)

Publica a Maven Central directamente desde tu máquina, sin CI:

# 1. Configura secretos cifrados (sops + age)
scripts/secrets.sh --action keygen --log-file /tmp/ether-deployment-hub/secrets.log
scripts/secrets.sh --action edit   --log-file /tmp/ether-deployment-hub/secrets.log
 
# 2. Release completo (plan + deploy por niveles + verificación de publicación)
just release

Los pasos intermedios son make release-build, just publish-central y just verify-published. Ver spec-native/COMMANDS.md para el detalle.

Uso en tu proyecto

Con ether-parent como POM padre

<parent>
  <groupId>dev.rafex.ether.parent</groupId>
  <artifactId>ether-parent</artifactId>
  <version>8.0.0</version>
  <relativePath/>
</parent>
 
<dependencies>
  <!-- Servidor HTTP completo -->
  <dependency>
    <groupId>dev.rafex.ether.http</groupId>
    <artifactId>ether-http-jetty12</artifactId>
  </dependency>
 
  <!-- WebSocket -->
  <dependency>
    <groupId>dev.rafex.ether.websocket</groupId>
    <artifactId>ether-websocket-jetty12</artifactId>
  </dependency>
 
  <!-- APM con Glowroot (provided — requiere -javaagent) -->
  <dependency>
    <groupId>dev.rafex.ether.glowroot</groupId>
    <artifactId>ether-glowroot-jetty12</artifactId>
  </dependency>
</dependencies>

Con ether-parent como BOM (sin heredar)

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>dev.rafex.ether.parent</groupId>
      <artifactId>ether-parent</artifactId>
      <version>8.0.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

Ejemplo completo — servidor de producción mínimo

public class Application {
 
    public static void main(String[] args) throws Exception {
        // 1. Configuración
        var config = EtherConfig.builder()
            .source(new YamlFileConfigSource("config.yaml"))
            .source(new EnvironmentConfigSource())
            .build()
            .bind("app", AppConfig.class);
 
        // 2. Infraestructura
        var codec    = new JacksonJsonCodec();
        var verifier = new DefaultTokenVerifier(JwtConfig.fromConfig(config));
 
        // 3. Seguridad
        var security = HttpSecurityProfile.builder()
            .cors(CorsPolicy.allowOrigin(config.allowedOrigin()))
            .securityHeaders(SecurityHeadersPolicy.strict())
            .build();
 
        // 4. Rutas
        var routes = List.of(
            EtherRoute.get("/health",    new HealthResource()),
            EtherRoute.get("/users",     new ListUsersHandler(userRepo)),
            EtherRoute.get("/users/:id", new GetUserHandler(userRepo)),
            EtherRoute.post("/users",    new CreateUserHandler(userRepo))
        );
 
        // 5. Instrumentación Glowroot (opcional)
        var glowroot = GlowrootJettyHandler.builder()
            .healthPath("/health")
            .requestIdHeader("X-Request-Id")
            .defaultSlowThreshold(2_000)
            .build();
 
        // 6. Servidor
        var server = JettyServerFactory.create(
            JettyServerConfig.of(config.port()),
            routes, codec, verifier, security,
            new UuidRequestIdGenerator(),
            new Slf4jTimingRecorder(),
            List.of(glowroot::wrap)
        );
 
        // 7. Arranque con shutdown graceful
        new JettyServerRunner(server).start();
    }
}

Ether Framework Unified API docs for Ether modules