DEV Community: Jean Carlo Vittory Laguna

Embeddings y RAG en aplicaciones web

Jean Carlo Vittory Laguna — Sat, 08 Nov 2025 04:19:21 +0000

Quiero esta vez escribir un poco sobre el proceso de construcción de una pequeña idea que use para poder comprender el uso de embeddings y RAG en aplicaciones web que requieran este tipo de tecnologías.

Buscando entender un poco estos conceptos encontré la idea de poder ayudar a mejorar la experiencia de usuarios que necesiten llevar al siguiente nivel sus procesos de capacitación o uso de procesos sistemáticos que se encuentren alojados en archivos PDF o word a través de una plataforma que ponga a disposición un chatbot que contenga toda la información de estos archivos y el usuario pueda realizar preguntas sobre ellos de forma natural y logre recibir una respuesta.

Segun esta necesidad encontre que los embeddings y el uso de RAG en chatbots con IA logran no solo cubrir esta necesidad sino abrir un abanico de opciones para poder llevar esta idea a niveles superiores.

En un primer momento el flujo fue muy sencillo:

En la anterior imágen encontramos

3 nodos que representan a openai
2 nodos que representan endpoints de nuestra aplicación
2 nodos que representa nuestra base de datos vectorial
1 nodo que representa una base de datos tipo postgreSQL

Ahora bien, lo primero que debemos resaltar son los nodos de openai ya que estos nos permiten generar los embeddings y además de esto la respuesta final que le entregaremos al usuario.

Los nodos que representan la base de datos vectorial nos permiten almacenar estos datos vectorizados, en este caso estamos usando postgreSQL, para poder consultarlos y de esta forma alimentar a openai con esta informacion y lograr dar con una respuesta concreta al usuario.

El nodo de postgreSQL nos permite almacenar datos del documento almacenado para poder mostrar al usuario en una UI el listado de documentos en el sistema.

Por último los 2 nodos que representan los endpoints son las puertas de entrada y salida para poder consumir todo estos recursos desde nuestra aplicación.

Paremos un momento e intentemos revisar detalladamente el papel de los 3 nodos de openai. Estos, como ya lo nombramos, cumplen dos funciones: Realizar el proceso de creación del embedding y generar la respuesta final del usuario a través del chat. Pero ¿Qué es un embedding y porque debemos de utilizar esta técnica para lograr nuestro objetivo?

Un embedding en pocas palabras es la representación numérica de cada palabra de nuestro elemento a almacenar. Esta representación no es arbitraria ya que, usando matematica de vectores, logra llegar a una representación numerica de cada palabra.

Para lograr esto, empresas como Openai, Anthropic o Google nos proveen de modelos especializados en embeddings. Muy similar a los modelos que siempre escuchamos como GPT-4o, Sonnet o Gemini existen modelos para embeddings. En este caso estaremos utilizando el modelo text-embedding-3-small de openai sin embargo existen muchos otros y su uso dependera del objetivo de nuestra aplicación y el presupuesto que tengamos a disposición.

Por ejemplo text-embedding-3-small es un modelo de uso general y economico con 1536 valores por vector pero si vamos a modelos como text-embedding-3-large encontramos un modelo mas preciso con 3072 valores por vector pero en ese mismo sentido el procesamiento es mas costoso.

Ademas de esto debemos tener en cuenta factores como el dominio de entrenamiento del modelo, soporte en varios idiomas o capacidad semantica.

Una vez acalarado esto debemos almacenar nuestros vectores en una base de datos que nos permita almacenar este tipo de datos y para ello usamos PostgreSQL a través de su extensión pgvector

create extension if not exists vector;

Sin embargo, tenemos bases de datos que soportan nativamente vectores como es el caso de Pinecone o Chroma. Para este caso decidimos usar PostgreSQL porque estamos utilizando Supabase como BaaS y así proveernos de sus diferentes features para un desarrollo más rápido.

Dentro de esta tabla de Postgres, utilizando nuestra extensión de pgvector, ya podemos generar columnas que nos almacenen este nuevo tipo de dato. Por ejemplo, para nuestro caso tenemos nuestra tabla definida así:

create table if not exists document_sections (
  id               bigserial primary key,
  document_id      bigint not null references documents(id) on delete cascade,
  section_order    int not null,                      
  section_content  text not null,                     
  embedding        vector(1536) not null,            
  meta             jsonb not null default '{}'::jsonb,
  created_at       timestamptz not null default now()
);

Como puedes observar nuestro embedding se almacenará aquí:

embedding vector(1536) not null

En donde el número 1536 representa la cantidad de elementos que existirán dentro de cada vector.

Vale, ahora debemos de hablar de algo muy importante en este punto y es algo llamado chunk. Tanto nuestro modelo de embedding como nuestra tabla de vectores no almacena todo el documento de golpe ya que si el usuario llega a cargar un documento muy grande la exigencia de computo sería enorme, la precision a la hora de realizar busquedas se veria afectada y, además de esto, debemos de tener en cuenta que estos modelos de embeddings tambien tienen un máximo de tokens por lo tanto no podemos procesar tokens de manera infinita.

Para ello nos vemos en la necesidad de procesar los datos por chunks. Para lograr esto tenemos múltiples caminos. Implementar nuestro propio "chunker" o utilizar uno de alguna libreria. Para este caso decidí crear mi propio "chunker" ya que no es un producto con pretensiones comerciales pero facilmente puedes utilizar sentence-splitter.

La tarea de realizar chunks es muy importante ya que de esta depende el nivel de precision que existira en los vectores. Debes de tener en cuenta que realizar cortes muy grandes genera distorsion y sesgo a la hora de realizar busquedas vectoriales pero si realizamos cortes muy pequeños perdemos contexto global de nuestro texto, responder a preguntas generales se vuelve complejo y debemos de procesar más embeddings lo cual nos genera mas costos.

Vale, entonces hagamos un paso a paso del funcionamiento de nuestra aplicación. En esta primera parte describiremos el proceso de uploading:

El usuario hace un upload del documento desde la UI
Se envían estos datos al servidor usando el endpoint send-file
Una vez dentro de send-file ejecutamos el chunk de nuestro archivo y por cada chunk generamos un embedding.
Insertamos nuestro embedding en la base de datos vectorial.
Insertamos en nuestra tabla convencional de postgres los datos del archivo para mostrar en la UI.

En este punto ya con nuestro archivo en nuestra base de datos podemos consultarlo y para ello recurrimos a los siguientes pasos

El usuario realiza una pregunta en el chat
Esta pregunta la transformamos en un embedding
Usamos este embedding generado y realizamos un busqueda vectorial en nuestra base de datos vectorial con el fin de encontrar similitudes entre el embedding generado por la pregunta y los embeddings almacenados en nuestra base de datos
Usamos un LLM para procesar tanto la respuesta de la busqueda vectorial utilizada aqui como contexto y la pregunta a responder enviada inicialmente por el usuario.
La respuesta generada la devolvemos al cliente.

De esta forma cerramos el ciclo de nuestra aplicación y como puedes ver estamos utilizando un modelo de LLM alimentando con los datos de nuestra base de datos vectorial para generar una respuesta que se limite solamente a estos datos. En nuestra aplicación esta última sección luce algo así:

    const aiResponse = await openai.chat.completions.create({
      model: "gpt-4o-mini",
      temperature: 1,
      max_completion_tokens: 150,
      messages: [
        {
          role: "system",
          content:
            "Use the context if it exists. If the context contains 'NO_COINCIDENCE', thank the user and kindly explain that you cannot respond with the information available.",
        },
        {
          role: "user",
          content: `
                Using the following information please answer the question: 
                Context: ${context}
                Question: ${message}
          `,
        },
      ],
    });

Habras notado que utilizamos un termino busqueda vectorial al cual no nos hemos referido hasta el momento. Existen 3 tipos de busquedas vectoriales que podemos llegar a aplicar:

Similitud del coseno (Cosine similarity)
Producto interno (Dot product)
Distancia euclidiana (Euclidian distance)

Cada una de estas tres opciones tiene su objetivo, para nuestro caso aplicamos la busqueda por similitud del coseno. Este algoritmo nos permite realizar busquedas por angulo entre dos vectores e ignora la longitud de los mismos. En otras palabras dentro del plano vectorial si el angulo entre dos vectores es pequeño representa similitud, por el contrario si es mayor o totalmente opuesto representan menos similitud o directamente significados totalmente opuestos.

Por lo general en embeddings se tiende a utilizar la similitud por coseno ya que nos interesa mas la direccion semantica (angulo) más que la longitud del vector ya que este algoritmo normaliza esta longitud por defecto haciendo que este valor pierda importancia.

Se debe de tener en cuenta que esta normalización tiene un costo y, si bien es el algoritmo más utilizado, el producto interno tiene un mayor rendimiento pero la longitud al no estar normalizada puede llegar a introducir sesgos o alucinaciones.

En nuestro caso hemos diseñado esta consulta a traves de un procedimiento almacenado en supabase utilizando la similitud del coseno.

Una vez repasado de manera somera el flujo de nuestra aplicación podemos empezar a ver que factores extra nos podemos llegar a ecnontrar y como los podemos resolver.

Uno de los principales inconvenientes que podemos llegar a enfrentar es no bloquear al usuario durante todo este poceso ya que, como puedes llegar a imaginar, el tiempo que trascurre entre subir el archivo y generar los embeddings puede tomar un tiempo dependiendo de la velocidad de red que haya en ese momento y la disponibilidad del servicio de openai.

En ese sentido, para no bloquear al usuario podemos generar un sistema de colas que nos permitan desacoplar este proceso y, a través de un estado de carga, avisar al usuario cuando el archivo ya se encuentra listo para su consulta.

Para lograr esto podemos utilizar servicios como SQS de AWS o algun broker de mensajeria como RabbitMQ. Ya depende de tus necesidades y presupuesto.

Para nuestro caso hemos decidido mantenerlo simple y usamos un servicio de mensajeria de Upstash llamado Qstash lo cual nos permitio desacoplar nuestro sistema sin necesidad de crear una infraestrcutura manteniendo simple nuestra implementación.

Otro posible problema que puedes llegar a enfrentar es que si trabajas con servicios serverless como Lambdas o endpoints de Next estos tienen un limite de datos que se pueden llegar a transmitir en cada petición, por lo tanto enviar archivos PDF o docx puede generarte problemas de tipo HTTP 413 "Content Too Large". Para solucionar esto puedes usar servicios como S3 de AWS o Google Storage en GCP. Lo que implementamos nosotros fue: Desde el cliente subir el archivo a un bucket en supabase con un storagePath y, en el punto en el que necesitamos generar el embedding ya del lado del server, consultamos este bucket, descargamos el archivo y generamos el embedding y asi no tenemos que recurrir a envios de red muy grandes que pueden afectar el rendimiento de nuestra aplicación.

Por último te dejo el diagrama final de la aplicacion en donde se detalla la interacción de cada componente:

Model Context Protocol: Parte I Creando un Servidor MCP

Jean Carlo Vittory Laguna — Wed, 23 Apr 2025 22:34:06 +0000

Anthropic ha lanzado un nuevo protocolo de comunicación para modelos de IA llamado Model Context Protocol el cual nos permite brindarle información, contexto y herramientas a LLMs que requieren flujos complejos para lograr respuestas fnales.

En este ciclo de post veremos como crear servidores MCP (MCP Servers) y clientes MCP (MCP Clients) para lograr, por medio de un prompt, que un LLM pueda acceder a herramientas creadas por nosotros y, a través de ellas, se conecte a APIS externas para obtener información en tiempo real o ejecute cualquier código que nosotros construyamos y así lograr una respuesta con base en dicha información consultada.

Model Context Protocol

Como puedes ver en la imágen anterior tenemos algo llamado clientes MCP que se conectan, a través del protocolo MCP, a un servidor MCP y este tiene acceso a bases de datos, sistemas de archivos o puede realizar llamadas a una API externa. Pero, ¿qué es un cliente y un servidor MCP?

Cliente MCP

Un cliente MCP es básicamente Claude Desktop, Github Copilot o en su defecto una aplicación o componente de software creado por nosotros mismos. Este cliente es el encargado de recibir el prompt del usuario y conectarse al servidor MCP el cual es el que almacena en su interior las Tools que están disponibles para ser ejecutadas y realizar acciones ya sea sobre nuestro sistema de archivos, una base de datos o solicitudes a través de la web.

Los permisos de estas acciones deben estar configurados en nuestro servidor MCP.

Servidor MCP

Dicho lo anterior, el servidor MCP es el encargado de almacenar tres tipos de datos para que estén disponibles al cliente MCP:

Resources
Prompts
Tools

Hasta ahora hemos hecho un esbozo de lo que significan las Tools en el contexto de los MCP pero ¿Qué son los Resources y los Prompts?

Resources

Los Resources o Recursos son datos que expone el servidor al cliente para que este los lea y use como contexto para el LLM. En ese sentido los recursos pueden ser:

Archivos
Registros de bases de datos
Respuestas de una API
Logs
entre otros

Si deseas aprender más sobre Resources lee esto

Prompts

Los prompts en este contexto son prompts templates que podemos almacenar en nuestro servidor y exponerlos al cliente para que los pueda usar y, de esta forma, mantener una cohesión a la hora de realizar ciertas tareas dentro del flujo de nuestro sistema.

Si deseas aprender más sobre Prompts lee esto

Tools

Por último, las Tools. Debemos pensar estas como funcionalidades almacenadas en nuestro servidor MCP para poder ejecutar diferentes tipos de operaciones:

Interactuar con APIS externas.
Realizar operaciones de computo.

En otras palabras, estas herramientas no son más que funciones, como las que hemos construido siempre, almacenadas y listas para ser ejecutadas por el servidor MCP si el LLM asi lo decide.

Si deseas aprender más sobre Tools lee esto

En este post estarémos enfocados en el uso de Tools principalmente.

Ahora bien, ¿cómo definimos estas herramientas en nuestro servidor MCP? Cuando usamos algún sdk de model context protocol la definición de estas herramientas tiene su propia sintaxis las cuales puedes ver aquí:

Para nuestro caso definiremos nuestro servidor MCP usando el SDK de Python:

from mcp.server.fastmcp import FastMCP
from dotenv import load_dotenv
from utils.helpers import fetch_url, search_web
from constants import  SERPER_URL, docs_urls

load_dotenv()

mcp = FastMCP("docs")

@mcp.tool()
async def get_docs(query:str, library:str):
    """
    Search the documentation for a given query and library,
    Supports Langchain, Openai, llama-index.

    Args:
        query: The query to search (e.g: Chroma DB)
        library: The library search in (e.g: Langchain)

    Returns:
        The information from the documentation.
    """

    if library not in docs_urls:
        raise ValueError(f"The library {library} is not supported.")

    query = f"site:{docs_urls[library]} {query}"
    search_web_results = await search_web(query=query, url=SERPER_URL)

    if "error" in search_web_results:
        raise ValueError(f"Something went wrong: {search_web_results["error"]}")

    text = ""
    for result in search_web_results["organic"]:
        text += await fetch_url(result["link"])
    return text 

def main():
    mcp.run(transport="stdio")


if __name__ == "__main__":
    main()

En el código anterior podemos observar 5 aspectos importantes:

La definición de nuestro MCP server.
La creación de una herramienta o Tool para nuestro MCP Server.
Validaciones dentro de nuestro MCP server.
La creación de funciones utilitarias para modularizar la tarea de nuestra herramienta.
El runner de nuestro MCP Server utilizando un concepto que veremos mas adelante llamado transport.

veamos punto por punto.

Definición de nuestro MCP server

Para crear nuestro servidor es necesario instalar la dependencia necesaria

pip install "mcp[cli]"

Una vez instalada debemos importar la clase FastMCP así:

from mcp.server.fastmcp import FastMCP

y una vez importada instanciamos nuestro servidor:

mcp = FastMCP(name="docs")

El parámetro name puede ser cualquiera que desees

Creación de herramienta

Para crear una herramienta necesitamos definir una función y anteponer la directiva:

@mcp.tool()

Esto le permite al servidor identificar que la función es una herramienta y así diferenciarla de los resources o prompts que vimos anteriormente.

Por otro lado es importante definir el docstring de manera clara, correcta y precisa. Proveer metadata sobre lo que hace la función, los argumentos que recibe y lo que se espera devolver como resultado. Entre más especifica sea la información que le proveamos al docstring el LLM tendrá más contexto para saber que herramienta ejecutar según el prompt que se haya usado.

En nuestro caso la herramienta recibe dos parámetros query y library los cuales son:

Query: Tópico que se desea consultar.
Library: Documentación o librería sobre la cual se desea consultar el tópico.

Estos dos parámetros son los que el LLM debe de identificar sobre el prompt utilizado y para ello es necesario una buena descripción de la herramienta usando los docstring.

Validaciones dentro de nuestro MCP server

Como puedes observar una herramienta de nuestro servidor MCP se comporta como una función comun y corriente por lo tanto dentro de ella podemos realizar validaciones y manejar errores de una manera convencional. En este caso levantamos dos casos de error:

if library not in docs_urls:
        raise ValueError(f"The library {library} is not supported.")

if "error" in search_web_results:
        raise ValueError(f"Something went wrong: {search_web_results["error"]}")

Para la primera validación usamos una variable llamada docs_urls para centralizar y modularizar las posibles librerías que el usuario puede consultar. Esta variable no es mas que una lista definida así:

docs_urls={
    "langchain": "python.langchain.com/docs",
    "llama-index": "docs.llamaindex.ai/en/stable",
    "openai": "platform.openai.com/docs"
}

En este punto es bueno realizar énfasis en que al tener unos buenos metadatos en el docstring podemos lograr que el modelo identifique dentro del prompt la librería que el usuario desea consultar y así logre almacenarla dentro del parámetro library y de esa forma nosotros poder usarlo dentro de nuestras validaciones internas.

Funciones utilitarias

Como ya hemos resaltado nos encontramos frente a una función de python comun y corriente la cual podemos manipular de tal forma que nos permite modularizar los procesos que esta necesite realizar. En nuestro caso hemos abstraido dos procesos search_web y fetch_url.

Para la primera función utilizamos Serper como buscador de google con el fin de recuperar las 2 primeras URLs que coincidad con la busqueda del usuario. Para esto lo hacemos asi

    query = f"site:{docs_urls[library]} {query}"
    search_web_results = await search_web(query=query, url=SERPER_URL)

formateamos la variable query utilizando un operador de busqueda avanzada de google el cual nos permite buscar solo dentro de la URL que recuperamos de nuestra lista asi:

docs_urls[library]

Una vez formateado esta variable lo pasamos como parámetro a la función search_web_results junto con la URL de serper. Ya por dentro de la función encontramos este código:

async def search_web(query:str, url:str) -> dict | None:
    payload = json.dumps({"q": query, "num": 2})
    headers= {
        "X-API-KEY": os.getenv("SERPER_API_KEY"),
        "Content-Type": "Application/json"
    }
    async with httpx.AsyncClient() as client:
        try:
            response = await client.post(
                url, 
                data=payload, 
                headers=headers, 
                timeout=30.0
            )
            response.raise_for_status()
            return response.json
        except httpx.TimeoutException():
            return {"error": "Timeout error searching web"}
        except httpx.HTTPStatusError as e:
            return {"error": f"Error: {e.response.status_code}"}

EL cual no es más que una llamada a la API de Serper para que nos devuelva los 2 primeros resultados de la búsqueda.

Nuestra segunda función fetch_url se ejecuta después de devolver los resultados de search_web la propiedad que necesitamos, siguiendo la documentación de Serper, es organic la cual es una lista que contiene otra pripiedad llamada link y son estos links, en nuestro caso 2, los que utilizaremos como parámetros de nuestra segunda función fetch_url. Lo anterior lo encontramos definido aquí:

    search_web_results = await search_web(query=query, url=SERPER_URL)

    if "error" in search_web_results:
        raise ValueError(f"Something went wrong: {search_web_results["error"]}")

    text = ""
    for result in search_web_results["organic"]:
        text += await fetch_url(result["link"])

Como podemos observar nuestra función fetch_url se ejecuta dentro de un ciclo for utilizando la lista search_web_results["organic"]. Ya por dentro la función fetch_url luce así:

async def fetch_url(url:str):
    try:
        async with httpx.AsyncClient() as client:
            response = await client.get(url=url, timeout=30.0)
            response.raise_for_status()
            soup = BeautifulSoup(response.text, "html.parser")
            text = soup.get_text()
            return text 
    except httpx.TimeoutException():
        return {"error": "Timeout Error fetching url"}

Esta función realiza una solicitud HTTP a las URLs obtenidas en la primera función y, por medio de Beautiful Soup, parseamos el HTML a texto y lo devolvemos como respuesta de la misma función.

Por último el resultado de la función fetch_url lo devolvemos como respuesta final de la MCP Tool.

Transport

Por último nuestro código define el tipo de transporte que nuestro MCP Server utilizará. Para nuestro caso utilizamos el transporte tipo stdio el cual es un standard I/O que se recomienda usar cuando nuestro servidor MCP esta enfocado a aplicaciones por CLI o que corren de manera local en nuestro sistema realizando integraciones.

Se debe tener en cuenta de que existe otro tipo de transporte llamado SSE que está enfocado a conexiones entre el servidor MCP y un cliente MCP por medio de solicitudes POST.

Si deseas conocer más sobre transportes mira esto.

Vale hasta aquí hemos construido nuestro servidor MCP pero surgen 2 preguntas

¿Cómo lo usamos?
¿Dónde entra la IA en todo esto?

Como se nombro al principio estos servidores MCP se pueden utilizar ya sea con cliente creado por nosotros mismos o con alguna aplicacion de LLMs como Github Copilot o Claude Desktop.

En esta primera parte explicarémos como integrar nuestro servidor MCP con Github Copilot y en una segunda parte abordaremos la creación de un cliente personalizado que utiliza Express para comunicarse con nuestro servidor MCP.

Instalación con Github Copilot

Realmente es muy sencillo. Debemos primero asegurarnos tener las extensiones correspondientes de Github Copilot en VsCode y haber configurado nuestra cuenta para tener acceso a Copilot.

Luego de esto, debemos dirigirnos al archivo, dentro de vscode, llamado settings.json el cual se puede acceder así:

Damos click en Open user settings (JSON) y nos abrirá nuestras configuraciones de Vscode en formato JSON. Lo que harémos sera agregar al final de este archivo una nueva propiedad llamada mcp así:

"mcp": {
  "servers":{
    "documentation":{
      "command": "",
      "args": [
        "--directory",
        "",
        "run",
        "src/main.py"
      ]
    } 
  }
}

Como puedes ver nos hace falta completar dos valores command y la tercera posición del array args. Para obtener estos valores sigue esto pasos:

Para la propiedad command, si utilizaste uv como package management, corre en tu terminal el comando which uv y pega esa ruta en la propiedad command
para la segunda posición del array args debes de pararte en la carpeta en donde está tu servidor MCP y correr el comando pwd. Pega esa ruta en la segunda posición del array args.

Vale, pero ¿Qué es todo esto? Para poder utilizar nuestro servidor MCP con Copilot debemos especificarlo en nuestro settings.json para que copilot tenga acceso a él. Para ello definimos una propiedad mcp y dentro de ella otra propiedad llamada servers. En esta última listaremos todos los servidores que creemos para que Copilot pueda encontrarlos.

Cada servidor MCP que especifiquemos aquí debe de tener una configuración para que se corra cuando interactuemos con Copilot. Si utilizamos el ejemplo de nuestro ejercicio, al definir esto:

"documentation":{
      "command": "",
      "args": [
        "--directory",
        "",
        "run",
        "src/main.py"
      ]
    }

es como si corrieramos en nuestra terminal esto:

uv --directory <la ruta de tu proyecto mcp> run <el lugar en donde está tu main.py dentro del proyecto>

Al hacer esto, abriremos nuestro Copilot dentro de vscode y configuraremos el modo agent automaticamente se nos habilitará un icono al lado del input

AL dar click en este icono verémos todos nuestros MCP servers disponibles

Podemos habilitarlos y deshabilitarlos a nuestro gusto.

Es todo, ya podemos utilizar nuestro LLM con Copilot y este tendrá acceso a los MCP habilitados en nuestro sistema para utilizarlos si considera que para lograr una respuesta correcta a nuestro prompt debe de acceder a ellos como herramientas.

En una próxima entrega veremos como podemos conectar este MCP Server a un MCP Client que utiliza Express para capturar los prompts del usuario que provienen de cualquier cliente que se pueda comunicar por medio de HTTP. Logrando esto veremos el panorama completo del flujo de datos dentro del protocolo MCP utilizando un LLM de por medio para completar tareas que requiera nuestro usuario.

Si desean darle un vistazo al código completo desde el repositorio pueden hacerlo desde aquí.

AWS CDK + SAM: La combinación perfecta para desarrollar y depurar Lambdas localmente

Jean Carlo Vittory Laguna — Tue, 11 Mar 2025 19:01:27 +0000

Hace poco me vi en la necesidad de levantar una infraestructura de AWS usando su CDK debido a la sencillez de la API y la rapidez con la que se pueden definir y desplegar diferentes servicios.

Mi infraestructura contaba, entre otras cosas, con una serie de Lambdas conectadas a una base de datos de DynamoDB y, por lo pequeño del proyecto, decidí definir el código de las Lambdas en el mismo repositorio en donde realicé la configuración de mi infraestructura.

Cuando empecé a desarrollar la lógica de negocio de mi proyecto en las Lambdas, me encontré con que el CDK no cuenta con una forma per se de permitirte levantar un servicio local en tu máquina para poder hacer debug del código en las Lambdas.

Normalmente a lo que te lleva en un primer momento el flujo es a hacer debug sobre Cloudwatch, sin embargo, para ello debes de realizar un despliegue cada vez que necesitas revisar un log o solucionar un error en la etapa de desarrollo. Naturalemente no es efectivo trabajar de esta forma.

Aquí es donde entra SAM o Serverless Application Model. En pocas palabras es un framework de AWS para crear aplicaciones serverless usando IaC a través de su CLI y, aunque tenemos a la mano otras herramientas como localStack, me parecio interesante probar con SAM por ser una herramienta nativa de AWS que se integra facilmente con el CDK como lo veremos mas adelante.

¿Como funciona SAM?

Para poder levantar nuestros servicios definidos con el CDK necesitamos generar un archivo .yml en donde estarán descritos, en un formato YAML, todos los servicios y configuraciones que nuestra aplicación necesita.

Recordemos que cloudformation trabaja usando los servicios definidos a traves de YAML y SAM es por definicion una extensión de cloudformation.

Usando este archivo .yml SAM sabrá qué lambdas y servicios debe de levantar y bajo que configuraciones, permisos y conexiones a otros servicios debe contemplar.

Sin embargo, la historia no termina aquí ya que en este punto aparece un elemento fundamental para el funcionamiento de SAM el cual es Docker.

Docker le permite a SAM emular un entorno igual al que usa AWS para correr tus lambdas en sus servicios. Este entorno cuenta con librerías, un sistema operativo y configuraciones especificas del runtime que hayas seleccionado.

Si bien, podrias prescindir de Docker sin embargo tendrías que configurar tu mismo el entorno en local para poder correr el código de tus lambdas lo cual te llevaría a configuraciones complejas que Docker hace por ti.

En este punto podríamos enumerar los requisitos que necesitas para poder usar SAM:

AWS CLI
SAM CLI
Docker CLI

Troubleshooting de Docker

A veces sucede que nos acostumbramos a usar Docker Desktop, sin embargo es posible que al correr SAM este no pueda conectarse a Docker aún teniendo este último en ejecución arrojandonos un mensaje así:

Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

Para solventar este error debemos de revisar que la variable de entorno $DOCKER_HOST este disponible en nuestro sistema y, en caso de no tenerla disponible, definirla así en tu archivo de configuraciones del sistema:

export DOCKER_HOST=unix:///home/{user}/.docker/desktop/docker.sock

Si estás en un sistema Linux como Ubuntu puedes conocer tu usuario con el comando whoami. No olvides guardar el archivo y ejecutar:

source ~/.bashrc

o si usas zsh

source ~/.zshrc

Instalando SAM

Para instalar SAM solo basta con seguir las instrucciones en la documentacion. Aquí te mostrare las indicaciones para un OS Linux sin embargo en la documentacion referida encontrarás los pasos necesarios para tu sistema operativo.

Descarga el ZIP que encontrarás aqui en el apartado de Linux.
Una vez descargado descomprimelo usando unzip aws-sam-cli-linux-x86_64.zip -d sam-installation.
Ejecuta como sudo el archivo install sudo ./sam-installation/install
Por último verifica la instalación con sam --version

Generando el archivo YML

Para generar nuestro archivo YAML es muy sencillo. Una vez definidos nuestros servicios usando el CDK debemos ir a nuestra terminal y ejecutar el comando:

cdk synth

Esto nos devolverá toda nuestra infraestructura en formato YAML sin embargo necesitamos almacenar esta información en un archivo en la raíz de nuestro proyecto por lo tanto el comando para esto debe de ser este:

cdk synth --no-staging > template.yaml

El flag --no-staging le dice al CDK que no copie los assets necesarios para el despliegue ya que para nuestro caso no los necesitamos.

Levantando nuestro servidor en local

Nuestra plantilla de cloudformation ahora está en un archivo en la raíz de nuestro proyecto llamado template.yml para que SAM logre levantar el servidor basta con correr el comando:

sam local start-api

El comando anterior nos permite simular el comportamiento del servicio de AWS API Gateway lo cual nos abre un canal de comunicación HTTP para probar nuestros endpoints los cuales estan conectados a las lambdas usando, en una primera instancia el CDK de AWS, pero que SAM lee a través del template.yml.

Indicaciones finales

Si has seguido los pasos hasta aquí es posible que te encuentres con la situación de que al realizar cambios sobre tu lambda y probarlas en tu local no veas reflejados los cambios.

Esto sucede porque al correr el comando sam local start-api este genera un archivo llamado .aws-sam y si lo revisas te encontrarás en la carpeta build un archivo template.yaml al explorarlo te darás cuenta que las lambdas tienen una propiedad llamada Metadata y esta a su vez contiene una propiedad llamada aws:asset:path que te dirije a la carpeta cdk.out y si revisas en esta carpeta el archivo que ahí se especifica veras que el código que ésta contiene no tiene tus últimos cambios.

Para solventar esto debemos crear un pequeño script que nos permita hacer un rebuild de nuestro codigo actualizado para que SAM pueda leerlo. Este script luciría así:

#!/bin/bash pkill -f "sam local start-api" rm -rf .aws-sam rm -rf cdk.out cdk synth --no-staging > template.yaml sam build sam local start-api

Para nuestro caso lo podemos colocar en la raíz del proyecto y crear en nuestro package.json un script dev que lo ejecute cada vez que levantemos nuestro entorno de desarrollo.

Esto seria todo. Recuerda siempre tener Docker levantado para que el proceso sea exitoso.

JWT & Refresh Tokens 🔒

Jean Carlo Vittory Laguna — Sun, 24 Mar 2024 00:35:12 +0000

JWT o Json Web Token es un estándar para la autenticación y transferencia segura de datos entre dos partes. Usa la encriptación en base64 y una firma por medio de una clave privada o publico/privada para poder verificar la validez del token.

Estos tokens cuentan con una estructura en particular

El header o encabezado contiene la información del tipo de token utilizado y el tipo de algoritmo usado para la encriptación. Por otro lado, el payload o carga útil hace referencia a los datos suministrados por el desarrollador y cargados dentro del token en formato JSON. Por ultimo tenemos el signature o la firma que consiste en una clave secreta para ser usada como método de verificación de la validez del token.

Para mayor información referirse a: https://jwt.io/

Ahora bien, en el contexto de una aplicación que requiera un proceso de autenticación y autorización de usuarios por lo general hacemos uso de JWT para generar tokens los cuales cargamos, dentro del payload del token, con información que nos permita verificar en nuestra base de datos que esa persona sea quien dice ser o cuente con los roles y permisos que se requieren para acceder a un recurso en especifico.

Es importante resaltar que el payload utilizado no debe contener información susceptible del usuario como contraseñas, cuentas bancarias entre otras.

Para lograr esto por lo general tenemos un flujo similar a este

En la anterior imagen observamos como un cliente inicia sesión dentro de nuestra aplicación, enviando mediante una solicitud HTTP, un email y una contraseña la cual verificamos en nuestra base de datos y si dichos datos coinciden devolvemos un ACCESS_TOKEN el cual el cliente almacenara, ya sea en el local storage o en el session storage, y deberá enviar en cada solicitud que realice dentro de nuestra aplicación para autorizar el consumo de los recursos que requiera.

La forma en como enviar el ACCESS_TOKEN desde el servidor dependerá de tu aplicación. Este token puede ser enviado mediante cookies o mediante una respuesta HTTP ordinaria. Cada una tiene ventajas y desventajas que deben ser consideradas.

Este ACCESS_TOKEN contara con un tiempo de expiración el cual configuraremos de acuerdo a las necesidades tanto de seguridad como de experiencia de usuario que nuestra aplicación requiera.

Debemos considerar que entre mas largo sea el tiempo de expiración de nuestros tokens mas vulnerable será nuestra aplicación en términos de seguridad. Por otro lado, entre mas corto sea dicho tiempo, nuestros usuarios deberán hacer login nuevamente para obtener un ACCESS_TOKEN nuevo lo cual entra en detrimento de la experiencia de usuario.

REFRESH TOKENS

Hasta este punto no se ha dicho nada diferente a lo que es normalmente un sistema de autenticación y autorización común que implemente JWT.

Los refresh tokens nos permiten lograr que nuestro usuario no tenga que realizar un login nuevamente cada que el ACCESS_TOKEN expira y lo logra mediante el envío de un token extra o REFRESH_TOKEN cuando el usuario hace login.

La diferencia a este punto es que ambos tokens tienen un tiempo de expiración diferente. Mientras el ACCESS_TOKEN puede llegar a tener 20s el REFRESH_TOKEN puede llegar a tener 6 meses o 1 año de expiración y al vencerse el primer token el usuario utilizara el REFRESH_TOKEN como token de acceso para generar un nuevo ACCESS_TOKEN y de esta forma mantener activa la sesión dentro de nuestra aplicación.

Es posible llegar a pensar que esta solución no es realmente útil ya que simplemente aumentando el tiempo de expiración del ACCESS_TOKEN nos ahorraría tener que enviar un segundo token o podríamos pensar ¿Qué sucede si el REFRESH_TOKEN es hurtado? ¿No pondríamos en riesgo la seguridad de nuestro sistema al tener un tiempo de expiración tan largo?

¿Por qué enviar dos tokens de acceso?

Es importante resaltar que el REFRESH_TOKEN nos permite manejar un concepto llamado SESIONES dentro de nuestra aplicación la cual por lo general es una tabla en nuestra base de datos.

La idea de generar un segundo token es poder mediante este token generar un ACCESS_TOKEN nuevo para el usuario en caso de que dicho ACCESS_TOKEN haya sido expirado y solo generaremos un nuevo ACCESS_TOKEN si el usuario nos envía el ACCESS_TOKEN expirado y el REFRESH_TOKEN existe dentro de nuestro registro de sesiones y es valido como JWT.

Dicho lo anterior, nuestro proceso de autorización ahora no solo consultara la validez del REFRESH_TOKEN y del ACCESS_TOKEN o si el usuario que esta accediendo a los recursos de nuestra aplicación existe, sino que ahora consultara una tabla llamada SESIONES que almacenara los REFRESH_TOKENS activos y, si dicho token existe y esta activo, generara un nuevo ACCESS_TOKEN para acceder a los recursos de nuestra aplicación.

De esta forma estaremos generando ACCESS_TOKENS continuamente solo y solo si nuestro usuario cuente con un ACCESS_TOKEN valido y un REFRESH_TOKEN valido.

Debemos resaltar que no es lo mismo validez del token que tiempo de expiración del token. Nuestro token pudo haber expirado pero sigue siendo valido. Los JWT no pueden ser invalidados y solo podrán ser manejados mediante un tiempo de expiración lo cual no necesariamente quiere decir invalidez

¿Qué sucede si el `REFRESH_TOKEN` es hurtado? ¿No pondríamos en riesgo la seguridad de nuestro sistema al tener un tiempo de expiración tan largo?

Recordemos que la forma de acceder a nuestra aplicación es mediante el ACCESS_TOKEN y si este ha expirado generaremos otro nuevo mediante la validación del REFRESH_TOKEN. Por lo tanto solo podemos generar un nuevo ACCESS_TOKEN si contamos tanto con el ACCESS_TOKEN y el REFRESH_TOKEN valido.

Si un atacante logra hurtar nuestro ACCESS_TOKEN solo tardara 5s, o menos si así lo configuramos, para ser expulsado de la aplicación ya que no podrá generar uno nuevo al no tener el REFRESH_TOKEN.

Por otro lado, si un atacante logra hurtar nuestro REFRESH_TOKEN no podrá generar un ACCESS_TOKEN ya que, para generar uno, necesita el primer ACCESS_TOKEN generado al momento de hacer login.

Podemos observar aquí la importancia de tener un buen manejo de seguridad en nuestros tokens como por ejemplo:

Configurar tiempos cortos en el ACCESS_TOKEN.
Transferir nuestros tokens mediante las cabeceras HTTP.
Si usamos cookies asegurarnos de usar la bandera HttpOnly y secure para evitar ataques XSS.
Limitar el tiempo de expiración de nuestras cookies.

Llegados a este punto encontramos un flujo similar a este

Ahora veremos de que forma, desde el código, podemos actualizar nuestro ACCESS_TOKEN haciendo uso de nuestro REFRESH_TOKEN.

IMPLEMENTACIÓN

En este ejemplo utilizaremos Node y Express para ejemplificar este proceso y haremos toda nuestra lógica dentro del middleware de autorización. Debemos recordar que nuestro proceso de autenticación, donde estamos generando nuestros dos tokens, ya esta configurado y nos centraremos en como actualizar nuestro ACCESS_TOKEN utilizando nuestro REFRESH_TOKEN.

Sin embargo, debemos realizar un pequeño ajuste a nuestro proceso de autenticación ya que es aquí donde haremos el registro de nuestro REFRESH_TOKEN en la tabla que anteriormente llamamos SESIONES.

El código luce algo así:

Podemos observar como nuestro servicio de autenticación, que es llamado desde nuestro controlador de login, primero valida la existencia del usuario a través del método getUserByEmail.
Utilizando la librería bcrypt validamos la contraseña y, si este proceso arroja un error, devolvemos a través del manejador de errores el código correspondiente.
Si la validación de la contraseña fue bien registramos en nuestra tabla SESIONES, usando el método createSession, la sesión de nuestro usuario.
Como ultimo paso, firmamos ambos tokens y configuramos el tiempo de expiración para cada uno. Recordemos que el ACCESS_TOKEN por lo general cuenta con un tiempo muy corto de expiración y el REFRESH_TOKEN, por el contrario, se configura con un tiempo largo de expiración.

De esta forma tenemos nuestro proceso de autenticación ahora configurado para que nos devuelva ambos tokens y nos registre una sesión por cada usuario con un login activo.

Proceso de autorización

Por lo general tendemos a realizar el proceso de autorización, para cada uno de los recursos de nuestra aplicación, mediante un middleware. Es en este en donde en este ejemplo realizaremos todo el proceso de validación y generación ACCESS_TOKEN.

Una vez nuestro usuario haya accedido a nuestra aplicación y este haya guardado el ACCESS_TOKEN y el REFRESH_TOKEN utilizaremos nuestro middleware de autorización para validar si nuestro usuario cuenta con los permisos suficientes para consultar el recurso que esta solicitando.

En la anterior imagen observamos todo el proceso de autorización completo pero vamos a revisarlo linea por linea

En este ejemplo estamos enviando los tokens por medio de el header Authorization y un header personalizado que llamamos x-refresh-token por lo tanto lo primero que realizamos es la validación acerca de la existencia o no de ambos tokens. Si estos no existen, enviaremos un error de tipo Forbbiden.
En las siguientes lineas tenemos una segunda capa de validación en donde, usando la librería JOI, validamos si los datos dentro de estas cabeceras son de tipo string.
dentro del try...catch verificamos el ACCESS_TOKEN y accedemos a los valores payload y expired. Si el payload existe, creamos un valor nuevo dentro del objeto req que llamamos user y lo cargamos con lo que viene en el payload. Por último, ejecutamos la función next la cual nos permite avanzar al controlador.

Observemos que existe un @ts-ignore ya que para crear valores dentro del objeto Request de Express debemos realizar una configuración extra la cual no entra en el contexto de este blog. Si deseas saber más al respecto puedes leer como hacerlo aquí
Si ocurrió algún problema con la verificación de nuestro ACCESS_TOKEN nuestro método verifyJWT nos devolverá un objeto con el payload null y el expired jwt expired.
Luego de esto validamos de que si nuestra propiedad expired tiene un valor truthy y nuestro REFRESH_TOKEN fue validado con éxito validaremos nuestro REFRESH_TOKEN usando el método verifyWT. Caso contrario devolveremos un objeto con una propiedad payload en null.
Si nuestro REFRESH_TOKEN no fue validado con éxito devolveremos un error de Unauthorized.
Caso contrario, avanzaremos con nuestro flujo y consultaremos en nuestra base de datos el sessionId que venia en el payload de nuestro REFRESH_TOKEN y si esta consulta no encuentra ningún resultado volveremos a arrojar un error de tipo Unauthorized
Por el contrario, si nuestra consulta encuentra un sessionId activo firmaremos un nuevo ACCESS_TOKEN.
El payload de este nuevo token lo ingresaremos en la propiedad user de nuestro objeto Request
Por último, agregaremos este nuevo ACCESS_TOKEN dentro de la cabecera Authorization concatenando la palabra Bearer al inicio. Finalizaremos ejecutando la función next para avanzar a nuestro controlador.

De esta forma podemos crear un sistema de tokens el cual hace uso de los REFRESH_TOKEN. Si bien este sistema no es infalible podemos mejorar ciertos aspectos de nuestro sistema como lo hemos visto a través de esta lectura.

Gracias por leer 😊

Utiliza el patrón de diseño Strategy 👾

Jean Carlo Vittory Laguna — Sat, 09 Dec 2023 20:13:55 +0000

El patrón de diseño Strategy es una técnica utilizada para definir una serie de algoritmos, encapsularlos y así poder hacerlos intercambiables de acuerdo a las necesidades del usuario.

Este diseño hace parte de la familia de patrones comportamentales.

Podemos ejemplificar lo anterior imaginando que necesitamos definir, de acuerdo al método de pago de nuestro cliente, una serie de cálculos y acciones para poder ejecutar la transacción final.

A veces lo primero que se nos viene a la mente es utilizar un if...else y a partir de un parámetro de entrada definir distintos caminos en nuestro programa. Si seguimos esta idea pronto nos encontraremos con problemas de legibilidad, escalado y la refactorización puede llegar a ser compleja dependiendo de la complejidad de nuestro programa.

Por lo tanto el patrón Strategy nos permite encapsular acciones, según el método de pago elegido por nuestro cliente en nuestro ejemplo, y llamar una estrategia u otra. Si necesitamos ingresar otro método de pago que conlleve una serie de cálculos y procesos nuevos sólo basta con crear otra estrategia, con su respectivo algoritmo encapsulado y llamarlo.

Implementación

Para lograr lo anterior debemos partir de la idea de que el patrón Strategy usa como punto de partida una interfaz compartida por todas las diferentes estrategias que queramos crear.

Continuando con el ejemplo anterior, nuestra acción inicial es el proceso de pagos por lo tanto sabemos que esa acción será compartida por nuestras estrategias. Debemos generar una interfaz que describa dicha acción:

export interface IPaymentMethod {
  processPayment(paymentQuantity: number): Promise<string>;
}

Esta función nos devolverá un mensaje de ejemplo pero puedes modificarlo según sea tu caso

Luego de esto debemos crear nuestras estrategias las cuales implementarán en su interior un método, tal como lo describe la interfaz que creamos anteriormente, que se encargará de procesar, calcular y ejecutar lo que necesitemos según sea el caso.

import {
  IPaymentMethod,
  debitCardTypes,
  delaysDebitCards,
  creditCardTypes,
  delaysCreditCards,
} from "./interfaces";

export class CashStrategy implements IPaymentMethod {
  processPayment(paymentQuantity: number): Promise<string> {
    return new Promise((resolve) => {
      try {
        setTimeout(() => {
          resolve(
            `The payment was succesfully. You paid ${paymentQuantity} in cash`
          );
        }, 1000);
      } catch (error: any) {
        resolve("error");
      }
    });
  }
}

export class DebitCardStrategy implements IPaymentMethod {
  private debitCard: string;

  constructor(debitCardTypeInput: string) {
    this.debitCard = debitCardTypeInput;
  }

  processPayment(paymentQuantity: number): Promise<string> {
    const selectedCard = this.debitCard;
    if (
      Object.values(debitCardTypes).includes(selectedCard as debitCardTypes)
    ) {
      const delay = delaysDebitCards[selectedCard as debitCardTypes];
      return new Promise((resolve, reject) => {
        try {
          setTimeout(() => {
            resolve(
              `The payment was succesfully. You paid ${paymentQuantity} with ${selectedCard}`
            );
          }, delay);
        } catch (error: any) {
          reject("error");
        }
      });
    } else {
      throw "The selected card do not exist.";
    }
  }
}

export class CreditCardStrategy implements IPaymentMethod {
  private creditCard: string;

  constructor(creditCardTypeInput: string) {
    this.creditCard = creditCardTypeInput;
  }

  processPayment(paymentQuantity: number): Promise<string> {
    const selectedCard = this.creditCard;
    if (
      Object.values(creditCardTypes).includes(selectedCard as creditCardTypes)
    ) {
      const delay = delaysCreditCards[selectedCard as creditCardTypes];
      return new Promise((resolve, reject) => {
        try {
          setTimeout(() => {
            resolve(
              `The payment was succesfully. You paid ${paymentQuantity} with ${selectedCard}`
            );
          }, delay);
        } catch (error: any) {
          reject("error");
        }
      });
    } else {
      throw "The selected card do not exist.";
    }
  }
}

Hemos utilizado un setTimeout para simular un retraso en cada estrategia y simular un comportamiento asíncrono

Luego de crear las estrategias debemos crear la clase que instanciara nuestros pagos y desde allí ejecutaremos o seleccionaremos la estrategia que necesitemos:

import { CashStrategy } from "./strategys";
import { IPaymentMethod, IPayments } from "./interfaces";

export class Payments implements IPayments {
  public paymentMethod: IPaymentMethod = new CashStrategy();

  setPaymentMethod(paymentStrategy: IPaymentMethod): void {
    this.paymentMethod = paymentStrategy;
  }

  applyTransaction(paymentQuantity: number): Promise<string> {
    return this.paymentMethod.processPayment(paymentQuantity);
  }
}

Por defecto nuestra clase Payment instancia CashStrategy que se encarga de procesar transacciones en efectivo.

Por ultimo solo nos queda ejecutar nuestro programa e instanciar una u otra estrategia según sea el caso:

import { Payments } from "./payments";
import { DebitCardStrategy, CreditCardStrategy } from "./strategys";

const payment = new Payments();

const init = async () => {
  payment.setPaymentMethod(new CreditCardStrategy("American Express"));
  return await payment.applyTransaction(200);
};
init().then((result) => console.log(result));

Desventajas

Una de las principales desventajas de este patrón de diseño es que agrega un nivel de complejidad adicional al código en especial cuando tenemos múltiples estrategias y debemos coordinarlas entre ellas.

Al tratarse de clases, la configuración inicial y la conservación del estado entre las instancias puede llegar a ser un proceso complejo así como la compilación de nuestro programa cuando nuestras clases empiezan a aumentar.

A pesar de todo esto el patrón de estrategia nos permite solventar múltiples situaciones y si sabemos aplicarlos nos puede brindar soluciones a diferentes problemas que afrontamos como programadores.

Te adjunto el repositorio donde encontraras el código de este ejemplo.

Repositorio

Expandiendo la interfaz Request de Express con .d.ts

Jean Carlo Vittory Laguna — Fri, 26 May 2023 16:15:35 +0000

Hace poco me enfrente a una situación en la cual tenía un proyecto en Express con Typescript y uno de mis middlewares, especificamente el de autorización, debía obtener, de un JWT, el email del usuario y pasarlo al controlador de alguna forma.

Quería que dicho email llegara al controlador ya con el campo email dentro del objeto request de express con el fin de poder desestructurarlo de una manera más sencilla pero al intentar hacerlo me encontraba con el siguiente error:

¿Porqué sucede esto? Estamos intentando agregar un campo desconocido para el parámetro request de express, debemos recordar que estos campos están definidos en interfaces o tipos que el mismo express nos provee cuando instalamos la dependencia, por lo tanto, debemos lograr que dicha interfaz contemple el valor que queremos suministrarle a request y de esta forma el compilador de typescript nos permitirá agregar el campo que necesitamos ya que lo reconocerá dentro de la interfaz.

Usando archivos .d.ts

Para lograr el anterior objetivo podemos hacer uso de los archivos definition types de typescript. Estos archivos son aquellos que tienen como extensión .d.ts y son utilizados para definir tipos de datos y algunos casos de uso podrían ser:

Definir tipos de datos de librerías que están escritas en Javascript y se necesita que el compilador de typescript reconozca los datos de dicha librería. Un ejemplo de esto es el repositorio de definitelyTyped.
Migrar aplicaciones de Javascript a Typescript progresivamente. Los archivos .d.ts nos facilitan la migración de aplicaciones de Javascript a typescript al permitirnos centralizar los tipos de datos en archivos específicos, obteniendo así una fuente de documentación viva a la cual remitirnos con facilidad durante el proceso de migración.

Debemos resaltar que los archivos .d.ts no generan código de salida por lo tanto estos no terminaran en el código .js final.

En síntesis, un archivo definition type .d.ts nos facilita definir tipos tanto de nuestras aplicaciones como de librerías de terceros como lo veremos a continuación.

Extendiendo request de Express

Para poder solucionar el error mostrado anteriormente, cuando intentábamos crear un campo en el objeto request de express, debemos primero crear una carpeta que contendrá nuestros definitions types. En mi caso generé una carpeta @types en mi carpeta de configuración de express y dentro de ella sub carpetas para cada librería o archivo que necesite un .d.ts:

- src
  ... otros archivos
  - config
    - @types 
      - express
        - custom.d.ts
      ... otras carpetas para definición de tipos

Dentro de este archivo custom.d.ts debo generar el siguiente código:

declare namespace Express {
  interface Request {
    user: {
      email: string;
    };
  }
}

Puedes observar que estamos haciendo uso de declare namespace Express y dentro de las llaves definimos una interface de typescript, en este caso con el nombre Request, para agregarle los campos que necesitamos.

Al hacer uso de declare namespace Express estamos declarando un espacio de nombres, en este caso para la librería de Express, esto nos permite decirle al compilador de typescript que todo lo que declaremos dentro de este espacio corresponde a la librería de Express y de esta forma evitar colisiones, mejorar la modularidad de nuestro código y estructurar mejor las definiciones de tipos.

Ahora bien, debemos remitirnos a nuestro archivo package.json para definir la ubicación de nuestros tipos de datos y para ello debemos hacer uso de la propiedad "compilerOptions" así:

{
  ... 
  "compilerOptions": {
    "typeRoots": [
      "./src/config/@types"
    ]
  },
}

De esta forma el error desaparecerá y podremos agregar los campos que necesitemos al request de Express y así typescript podrá compilar nuestro código sin problemas.

Esto es todo. Espero sea de utilidad.

Cheers! :)

Acelera tus apps con Lazy Loading 🚀

Jean Carlo Vittory Laguna — Tue, 23 May 2023 05:17:58 +0000

Por lo general cuando creamos aplicaciones con React tendemos a usar rutas para que el usuario pueda acceder a diferentes vistas de nuestra aplicación. Para ello usamos, por ejemplo, el clásico navegador en la parte superior en donde podemos acceder al home, contacts, products o cualquier vista que queremos que el usuario acceda mediante un botón.

Nuestro código suele verse algo así cuando intentamos realizar el ejemplo anterior:

A simple vista pareciera que todo marcha bien, sin embargo cuando nuestra aplicación empieza a crecer y debemos incluir más rutas para nuestros usuarios nuestra aplicación empieza a perder rendimiento debido a que cada vez que ingresamos a ella cargamos todos nuestros componentes.

Podríamos detenernos y preguntarnos ¿realmente nuestro usuario al ingresar al home necesita que le carguemos los archivos javascript y css de articles y contact? debemos recordar que estos archivos afectan el rendimiento de nuestra aplicación y para lograr una optimización en este sentido se vuelve necesario evitar cargarle al usuario archivos innecesarios que afecten su experiencia.

Con base a lo anterior React nos provee una herramienta llamada Lazy que nos permite cargar los componentes solamente cuando el usuario los solicita después de la interacción con algún botón o acción que desate dicha solicitud.

Para implementar un lazy loading en nuestra aplicación debemos:

Importar la función Lazy desde React y pasarle mediante un callback los imports de cada unos de los componentes que queremos cargar dinámicamente

Es importante recordar que los exports desde cada uno de nuestros componentes deben ser por default

Si intentamos usar nuestra aplicación en este momento observaremos que al navegar entre las rutas la consola nos arrojará el siguiente error:

Para solucionar esto debemos realizar el siguiente paso:

Debemos importar un feature que nos provee React llamado Suspense el cual debe envolver nuestras rutas y a su vez permitirnos usar un fallback que se renderizará mientras nuestra aplicación realiza el fetching pertinente de archivos para poder renderizar el componente solicitado por el usuario en la vista. Nuestro código debe lucir así:

Si deseas aprender un poco más a profundidad sobre Suspense

Y eso es todo!

Debemos recordar que el lazy loading nos permite mejorar el performance de nuestras aplicaciones cuando estas tienen muchos componentes y no queremos cargarle al usuario cientos de archivos Javascript cuando realmente solo necesita unos cuantos para poder acceder a una vista en concreto.

Imports absolutos con React y Vite 🚀

Jean Carlo Vittory Laguna — Sat, 01 Apr 2023 20:01:34 +0000

Por lo general cuando nuestros proyectos en React empiezan a crecer nuestra estructura de carpetas empieza a ganar más anidamientos e importar archivos que se encuentran en otros directorios se torna así:

Esto hace que nuestro bloque de importaciones sea engorroso de leer y, si necesitamos cambiar alguna carpeta de lugar, se vuelve un dolor de cabeza ya que debemos analizar toda la ruta para evitar errores en la nueva importación.

Ahora bien, antes de entrar con la solución a este problema es importante entender qué es un import absoluto y qué es un import relativo.

IMPORT RELATIVO

Las importaciones relativas nos permiten traer archivos teniendo como punto de referencia la estructura propia de nuestro proyecto. Es decir, podemos importar archivos utilizando como punto de partida el archivo que define el import y navegar hacia el archivo objetivo por medio de ../.

IMPORT ABSOLUTO

Las importaciones absolutas nos permiten ya no tener como punto de partida el mismo archivo que necesita realizar la importación y, de esta forma, nosotros mismo navegar desde él hacia el archivo que deseamos importar sino que ahora utilizaremos una ruta raíz y desde ahí definiremos la ruta concreta a nuestro archivo objetivo, es decir, ya no navegamos desde el archivo que realizará el import hacia el archivo a importar sino que navegamos desde una ruta raíz definida hacia el archivo objetivo.

IMPORTS ABSOLUTOS EN REACT Y VITE

Cuando nuestro proyecto empieza a crecer es normal encontrarnos con estructuras de carpetas como esta:

¿Qué sucede cuando desde alguna página queremos acceder a un componente dentro de la carpeta components? si utilizáramos imports relativos caeríamos en el problema de tener un fila inmensa de ../../../../ hasta poder llegar a nuestro componente deseado. Debemos ahora cambiar esto a imports absolutos y para ello Vite nos provee una forma sencilla de hacerlo.

CONFIGURANDO VITE

Cuando generamos nuestro proyecto con vite se nos genera un archivo en la raíz llamado vite.config.js que luce así:

En este archivo debemos configurar nuestras rutas absolutas de esta forma:

Debemos usar la propiedad resolve para agregar un alias el cual es un array de objetos en donde cada objeto es una carpeta a la cual deseamos acceder desde cualquier parte de nuestro proyecto y no queremos utilizar un excesivo ../ para poder llegar a ella.

Dentro de cada objeto encontramos dos propiedades find: y replacement:. El primero es un string el cual nos permitirá nombrar ese alias para poder usarlo dentro de cada archivo que necesite usar la ruta absoluta. En nuestro caso usamos el @ cómo prefijo al nombre de la carpeta que queremos darle acceso absoluto desde cualquier parte de nuestro proyecto.

El segundo parámetro replacement: es la ruta desde vite.config.js la cual el alias representará. En nuestro caso recomendamos utilizar el modulo path y __dirname para normalizar este acceso desde la ruta raíz de cada maquina que ejecute nuestro programa.

Dicho esto nuestros imports pasarían de lucir así:

y ahora lucirían así:

Con Typescript

En el caso de utilizar typescript debemos realizar una configuración extra en nuestro archivo tsconfig.json:

Es importante resaltar que por cada alias agregado en el archivo vite.config.ts debemos agregar una propiedad más en paths dentro de tsconfig.json.

Eso es todo. Muchas gracias por leer.