1. Introducción y arquitectura

1.1 ¿Qué es EWeb?

EWeb es un framework web embebido para Free Pascal: el motor completo (enrutador, servidor HTTP, sesiones, plantillas, formularios, acceso a datos y contraseñas) se distribuye como una librería estática ya compilada (libeweb.a) que se enlaza directamente dentro del ejecutable de la aplicación. No hay proceso externo, ni runtime adicional, ni dependencias de terceros más allá de lo que trae Free Pascal (FCL-DB, SQLDB) y, si se usa EDB, la librería nativa de SQLite.

El resultado es un único binario autocontenido que sirve HTTP directamente.

Este manual documenta exclusivamente el uso de libeweb.a a través de su wrapper público, eweb/webapi.pas. No aborda la implementación interna del motor ni su compilación desde el código fuente.

1.2 Filosofía de diseño

• Wrapper delgado, motor opaco. El desarrollador nunca interactúa con la implementación interna (drivers de base de datos, parsing de plantillas, HMAC de sesiones, etc.). Todo eso vive dentro de libeweb.a. La aplicación sólo ve la unidad pública WebAPI.pas: clases como TEContext, TERouter, TEWebServer, TEDB, TEForm, TEPassword, y funciones globales (NewContext, CSRFToken).
• Seguro por defecto. Sesiones firmadas con HMAC-SHA1, cookies HttpOnly, comparaciones en tiempo constante para CSRF y contraseñas, SaveFileSafe que evita colisiones y path traversal, consultas SQL parametrizadas (?) en vez de concatenación de strings.
• Declarativo. El registro de middlewares y rutas se hace con llamadas explícitas y legibles: Router.Use(@SessionManager), Router.Get('/blog/{id}', @BlogDetail).
• JSON como lengua franca de datos. El acceso a base de datos (EDB) nunca expone datasets ni tipos de driver: todo lo que entra es SQL + parámetros, y todo lo que sale es TJSONData.

1.3 Componentes del framework

Toda la funcionalidad se consume a través de las clases y funciones expuestas por la unidad WebAPI (el wrapper público de libeweb.a):

1.4 Flujo de una petición

1. TEWebServer.Listen(puerto) inicia el servidor HTTP embebido.
2. Por cada request entrante, el motor construye un contexto interno y lo hace pasar por la cadena de middlewares registrados con Router.Use(...), en el orden en que fueron registrados.
3. Si la ruta empieza con /static/, el archivo se sirve directamente desde el directorio static/ del directorio de trabajo — no requiere handler ni ruta explícita.
4. En caso contrario, el router busca la primera ruta registrada que coincida con el método HTTP y el path (incluyendo parámetros {nombre}).
5. Se invoca el TWebHandler (procedure(ctx: Pointer)) asociado. Dentro del handler, la aplicación construye un TEContext con NewContext(HCtx) y trabaja con él (leer parámetros, consultar la base de datos, setear variables, renderizar una plantilla o responder JSON/texto/HTML).
6. Si nada coincide, el servidor responde 404.

1.5 Un vistazo mínimo

program HolaEWeb;

{$mode objfpc}{$H+}

uses
  WebAPI;

procedure Home(HCtx: Pointer);
var
  Ctx: TEContext;
begin
  Ctx := NewContext(HCtx);
  try
    Ctx.Text('Hola desde EWeb');
  finally
    Ctx.Free;
  end;
end;

var
  Router: TERouter;
  Server: TEWebServer;
begin
  Router := TERouter.Create;
  Router.Get('/', @Home);

  Server := TEWebServer.Create(Router);
  Server.Listen(8080);
end.

Este es el esqueleto mínimo de cualquier aplicación EWeb. El resto del manual construye sobre esta base: enrutamiento con parámetros, plantillas HTML, sesiones, formularios protegidos con CSRF, persistencia con SQLite y manejo de contraseñas.

1.6 Ediciones: Community y Premium

EWeb se distribuye en dos ediciones con la misma API de uso:

Este manual cubre la columna Community, que es la incluida en la libeweb.a de este paquete. Las capacidades marcadas como Premium se mencionan sólo como referencia de la hoja de ruta del producto.

--- Siguiente: 2. Instalación y compilación