From 199f29203530b64c955c2a222fba3093400fdbc1 Mon Sep 17 00:00:00 2001 From: Richard Zampieri Date: Mon, 26 Feb 2024 22:04:48 -0800 Subject: [PATCH] Adjust cookie tutorial --- docs/tutorials/cookies.md | 160 +++++++++++------- .../current/tutorials/cookies.md | 154 +++++++++++------ 2 files changed, 201 insertions(+), 113 deletions(-) diff --git a/docs/tutorials/cookies.md b/docs/tutorials/cookies.md index 2f8d248c..536b43a0 100644 --- a/docs/tutorials/cookies.md +++ b/docs/tutorials/cookies.md @@ -6,51 +6,7 @@ sidebar_position: 2 Cookies are small pieces of data that a website sends to a user's web browser while the user is browsing that website. Every time the user loads the website, the browser sends the cookie back to the server to notify the website of the user's previous activity. -Cookies serve several primary purposes: - -1. Session Management: -Cookies are often used to handle user sessions. For example, when you log into a website, a cookie is set to remember your login state. So, as you navigate the site, you remain logged in. - -2. Personalization: -Cookies can store user preferences to personalize the user's experience on the site. For example, cookies might store information about the user's preferred language, theme, or other settings. - -3. Tracking: -Some cookies track user behavior on the site over time. These are often used by third-party analytics tools to understand user behavior and optimize the site accordingly. Advertisers also use tracking cookies to display targeted ads based on user activity. - -4. Security: -Cookies can be used to support secure website functions. For example, a cookie can be used to remember that a user has authenticated to a site so that the server knows the user has already provided valid login credentials. - -It's also important to note that there are different types of cookies - session cookies, which expire when the browser session ends, and persistent cookies, which remain on the user's device for a set period of time or until they are explicitly deleted. - -:::caution USING COOKIES FOR TRACKING -Keep in mind that the use of cookies, especially for tracking and personalization, has raised privacy concerns, leading to regulations such as GDPR in Europe and CCPA in California that require sites to disclose their cookie usage and obtain user consent. -::: - -## Cookie-Parser Package - -- Ease of Use: cookie-parser makes it very easy to read cookie values, which are often used for tracking user sessions, personalization, and managing stateful applications. Without this library, you would have to manually parse the Cookie header and handle the nuances of cookie formatting. - -- Signed Cookies: The package also supports signed cookies, which are a way to verify the integrity of cookies (i.e., whether they have been tampered with). This is an important feature for securing sensitive information stored in cookies. - -## What to Consider When Using cookie-parser - -- Overhead: While it's not a heavy library, using cookie-parser does add a bit of overhead to each request, as it parses all cookies regardless of whether they are used in the route handler. - -- Stateful: Cookies inherently make an application stateful. When scaling an application, state can be problematic. Therefore, alternative stateless authentication methods, like tokens, can be preferable in a microservices architecture. - -## When to Use - -Deciding when to use cookie-parser largely depends on your application's needs. If your web application requires state management and you've chosen to do that via cookies, cookie-parser can make your life easier and your application more secure with signed cookies. - -However, if your website has heavy traffic, the overhead might become a concern. If your architecture is based around stateless services (common in microservices architectures), you might want to avoid cookies and opt for other methods of maintaining state, like JWTs (JSON Web Tokens). - -:::info -In case you're dealing with a high traffic website, consider alternatives like sessions stored in a database, JWTs, or tokens stored in HTTP headers. Also, using a load balancer to distribute traffic and session store modules to maintain session data across multiple servers can help to manage high traffic and stateful data. -::: - -The best approach often involves combining multiple techniques, tailored to your application's specific needs. Testing and monitoring your application under realistic conditions can help guide your decision-making process. - -## Use with ExpressoTS +## How to Use Cookies in ExpressoTS Install the npm cookie-parser middleware and type definition. @@ -59,18 +15,60 @@ npm i cookie-parser npm i -D @types/cookie-parser ``` -After the installation you can add the middleware to your ExpressoTS app. +### Add Middleware Globally + +**Non-opinionated template**: add the cookie-parser middleware in the `AppFactory` create method. ```typescript import cookieParser from "cookie-parser"; -// Add in the application create method in the middleware array -AppInstance.create(container, [cookieParser()]); +// Add middleware in the AppFactory create method +async function bootstrap() { + const app = await AppFactory.create(container, [cookieParser()]); + await app.listen(3000, ServerEnvironment.Development); +} + +bootstrap(); ``` -Here is an example of how to use cookie-parser: +**Opinionated template**: configure the cookie-parser middleware in the `App` provider class. In the opinionated template common `expressjs` middlewares are offered out-of-the-box. Explore the options in `this.middleware` property. + +```typescript +@provide(App) +export class App extends AppExpress { + private middleware: IMiddleware; + private provider: IProvider; + + constructor() { + super(); + this.middleware = container.get(Middleware); + this.provider = container.get(Provider); + } + + protected configureServices(): void { + this.middleware.addCookieParser(); + } + + protected postServerInitialization(): void { + if (this.isDevelopment()) { + this.provider.envValidator.checkAll(); + } + } + + protected serverShutdown(): void {} +} +``` -Set a cookie with a random UUID as value, that expires in 1 hour and is only accessible via HTTP: +### Add Middleware to a Route + +This is valid for both templates. You can add the cookie-parser middleware to a specific route. + +```typescript +@Get("get-cookie", cookieParser()) +getCookie(){}; +``` + +Let's create a route that set's a cookie with a random UUID as value, that expires in 1 hour and is only accessible via HTTP: ```typescript @httpGet("set-cookie") @@ -83,7 +81,7 @@ setCookie(@response() res: Response) { } ``` -Get a cookie: +Create a route that gets the cookie and returns the value: ```typescript @httpGet("get-cookie") @@ -93,18 +91,64 @@ getCookie(@cookies() cookieInfo: string, @response() res: Response) { ``` :::tip -Note that we are using `@cookies()` decorator to get the cookie information. This decorator is provided by inversify-express-utils. +`@cookies()` decorator it is a helper to get all cookies from the request. You can also use `@cookies('cookieName')` to get a specific cookie. +::: + +## What Are Cookies Used For? + +Cookies serve several primary purposes: + +1. Session Management: + Cookies are often used to handle user sessions. For example, when you log into a website, a cookie is set to remember your login state. So, as you navigate the site, you remain logged in. + +2. Personalization: + Cookies can store user preferences to personalize the user's experience on the site. For example, cookies might store information about the user's preferred language, theme, or other settings. + +3. Tracking: + Some cookies track user behavior on the site over time. These are often used by third-party analytics tools to understand user behavior and optimize the site accordingly. Advertisers also use tracking cookies to display targeted ads based on user activity. + +4. Security: + Cookies can be used to support secure website functions. For example, a cookie can be used to remember that a user has authenticated to a site so that the server knows the user has already provided valid login credentials. + +It's also important to note that there are different types of cookies - session cookies, which expire when the browser session ends, and persistent cookies, which remain on the user's device for a set period of time or until they are explicitly deleted. + +:::caution USING COOKIES FOR TRACKING +Keep in mind that the use of cookies, especially for tracking and personalization, has raised privacy concerns, leading to regulations such as GDPR in Europe and CCPA in California that require sites to disclose their cookie usage and obtain user consent. ::: +## Cookie-Parser Package + +- Ease of Use: cookie-parser makes it very easy to read cookie values, which are often used for tracking user sessions, personalization, and managing stateful applications. Without this library, you would have to manually parse the Cookie header and handle the nuances of cookie formatting. + +- Signed Cookies: The package also supports signed cookies, which are a way to verify the integrity of cookies (i.e., whether they have been tampered with). This is an important feature for securing sensitive information stored in cookies. + +## What to Consider When Using cookie-parser + +- Overhead: While it's not a heavy library, using cookie-parser does add a bit of overhead to each request, as it parses all cookies regardless of whether they are used in the route handler. + +- Stateful: Cookies inherently make an application stateful. When scaling an application, state can be problematic. Therefore, alternative stateless authentication methods, like tokens, can be preferable in a microservices architecture. + +## When to Use + +Deciding when to use cookie-parser largely depends on your application's needs. If your web application requires state management and you've chosen to do that via cookies, cookie-parser can make your life easier and your application more secure with signed cookies. + +However, if your website has heavy traffic, the overhead might become a concern. If your architecture is based around stateless services (common in microservices architectures), you might want to avoid cookies and opt for other methods of maintaining state, like JWTs (JSON Web Tokens). + +:::info +In case you're dealing with a high traffic website, consider alternatives like sessions stored in a database, JWTs, or tokens stored in HTTP headers. Also, using a load balancer to distribute traffic and session store modules to maintain session data across multiple servers can help to manage high traffic and stateful data. +::: + +The best approach often involves combining multiple techniques, tailored to your application's specific needs. Testing and monitoring your application under realistic conditions can help guide your decision-making process. + --- ## Support the Project ExpressoTS is an MIT-licensed open source project. It's an independent project with ongoing development made possible thanks to your support. If you'd like to help, please consider: -- Become a **[sponsor on GitHub](https://github.com/sponsors/expressots)** -- Follow the **[organization](https://github.com/expressots)** on GitHub and Star ⭐ the project -- Subscribe to the Twitch channel: **[Richard Zampieri](https://www.twitch.tv/richardzampieri)** -- Join our **[Discord](https://discord.com/invite/PyPJfGK)** -- Contribute submitting **[issues and pull requests](https://github.com/expressots/expressots/issues/new/choose)** -- Share the project with your friends and colleagues \ No newline at end of file +- Become a **[sponsor on GitHub](https://github.com/sponsors/expressots)** +- Follow the **[organization](https://github.com/expressots)** on GitHub and Star ⭐ the project +- Subscribe to the Twitch channel: **[Richard Zampieri](https://www.twitch.tv/richardzampieri)** +- Join our **[Discord](https://discord.com/invite/PyPJfGK)** +- Contribute submitting **[issues and pull requests](https://github.com/expressots/expressots/issues/new/choose)** +- Share the project with your friends and colleagues diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/tutorials/cookies.md b/i18n/pt/docusaurus-plugin-content-docs/current/tutorials/cookies.md index 20f7c5df..41caba48 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/tutorials/cookies.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/tutorials/cookies.md @@ -6,47 +6,7 @@ sidebar_position: 2 Cookies são pequenos pedaços de dados que um site envia para o navegador da web de um usuário enquanto o usuário está navegando nesse site. Sempre que o usuário carrega o site, o navegador envia o cookie de volta ao servidor para notificar o site da atividade anterior do usuário. -Os cookies servem a vários propósitos primários: - -1. Gerenciamento de sessão: Os cookies são frequentemente usados para lidar com sessões de usuário. Por exemplo, quando você faz login em um site, um cookie é definido para lembrar seu estado de login. Assim, enquanto você navega pelo site, você permanece logado. - -2. Personalização: Os cookies podem armazenar preferências do usuário para personalizar a experiência do usuário no site. Por exemplo, cookies podem armazenar informações sobre o idioma preferido do usuário, tema ou outras configurações. - -3. Rastreamento: Alguns cookies rastreiam o comportamento do usuário no site ao longo do tempo. Esses são frequentemente usados por ferramentas de análise de terceiros para entender o comportamento do usuário e otimizar o site de acordo. Anunciantes também usam cookies de rastreamento para exibir anúncios direcionados com base na atividade do usuário. - -4. Segurança: Os cookies podem ser usados para suportar funções seguras do site. Por exemplo, um cookie pode ser usado para lembrar que um usuário se autenticou em um site para que o servidor saiba que o usuário já forneceu credenciais de login válidas. - -Também é importante notar que existem diferentes tipos de cookies - cookies de sessão, que expiram quando a sessão do navegador termina, e cookies persistentes, que permanecem no dispositivo do usuário por um período de tempo definido ou até que sejam explicitamente excluídos. - -:::caution USANDO COOKIE PARA RASTREAMENTO -Tenha em mente que o uso de cookies, especialmente para rastreamento e personalização, levantou preocupações com a privacidade, levando a regulamentações como o GDPR na Europa e o CCPA na Califórnia que exigem que os sites divulguem seu uso de cookies e obtenham o consentimento do usuário. -::: - -## Pacote cookie-parser - -- Facilidade de Uso: o cookie-parser torna muito fácil ler valores de cookies, que são frequentemente usados para rastrear sessões de usuários, personalização e gerenciamento de aplicações com estado. Sem esta biblioteca, você teria que analisar manualmente o cabeçalho do Cookie e lidar com as nuances da formatação de cookies. - -- Cookies Assinados: O pacote também suporta cookies assinados, que são uma maneira de verificar a integridade dos cookies (ou seja, se eles foram adulterados). Esta é uma funcionalidade importante para garantir a segurança das informações sensíveis armazenadas nos cookies. - -## O que considerar ao usar o cookie-parser - -- Sobrecarga: Embora não seja uma biblioteca pesada, usar o cookie-parser adiciona um pouco de sobrecarga a cada requisição, pois ele analisa todos os cookies, independentemente de serem usados no manipulador de rota. - -- Estado: Os cookies, por natureza, tornam uma aplicação com estado. Ao escalar uma aplicação, o estado pode ser problemático. Portanto, métodos de autenticação alternativos sem estado, como tokens, podem ser preferíveis em uma arquitetura de microserviços. - -# Quando usar - -Decidir quando usar o cookie-parser depende em grande parte das necessidades de sua aplicação. Se sua aplicação web requer gerenciamento de estado e você escolheu fazer isso por meio de cookies, o cookie-parser pode facilitar sua vida e tornar sua aplicação mais segura com cookies assinados. - -No entanto, se seu site tem um tráfego pesado, a sobrecarga pode se tornar uma preocupação. Se sua arquitetura é baseada em serviços sem estado (comum em arquiteturas de microserviços), você pode querer evitar cookies e optar por outros métodos de manter o estado, como JWTs (JSON Web Tokens). - -:::info -Caso você esteja lidando com um site de alto tráfego, considere alternativas como sessões armazenadas em um banco de dados, JWTs, ou tokens armazenados em cabeçalhos HTTP. Além disso, usar um balanceador de carga para distribuir o tráfego e módulos de armazenamento de sessão para manter dados de sessão em vários servidores pode ajudar a gerenciar alto tráfego e dados com estado. -::: - -Assim como antes, a melhor abordagem geralmente envolve combinar várias técnicas, adaptadas às necessidades específicas de sua aplicação. Testar e monitorar sua aplicação sob condições realistas pode ajudar a orientar seu processo de tomada de decisão. - -## Uso com ExpressoTS +## Como Usar Cookies no ExpressoTS Instale o middleware cookie-parser npm e a definição de tipo. @@ -55,31 +15,73 @@ npm i cookie-parser npm i -D @types/cookie-parser ``` -Após a instalação, você pode adicionar o middleware ao seu aplicativo ExpressoTS. +### Adicione o Middleware Globalmente + +**Modelo não opinativo**: adicione o middleware cookie-parser no método de criação da aplicação no `AppFactory`. ```typescript import cookieParser from "cookie-parser"; -// Adicione no método de criação da aplicação no array de middleware -AppInstance.create(container, [cookieParser()]); +// Adicione o middleware no método de criação da aplicação +async function bootstrap() { + const app = await AppFactory.create(container, [cookieParser()]); + await app.listen(3000, ServerEnvironment.Development); +} + +bootstrap(); ``` -Aqui está um exemplo de como usar o cookie-parser: +**Modelo opinativo**: configure o middleware cookie-parser na classe provedora `App`. No modelo opinativo, os middlewares comuns do `expressjs` são oferecidos prontos para uso. Explore as opções na propriedade `this.middleware`. + +```typescript +@provide(App) +export class App extends AppExpress { + private middleware: IMiddleware; + private provider: IProvider; + + constructor() { + super(); + this.middleware = container.get(Middleware); + this.provider = container.get(Provider); + } + + protected configureServices(): void { + this.middleware.addCookieParser(); + } + + protected postServerInitialization(): void { + if (this.isDevelopment()) { + this.provider.envValidator.checkAll(); + } + } + + protected serverShutdown(): void {} +} +``` -Defina um cookie com um UUID aleatório como valor, que expira em 1 hora e é acessível apenas via HTTP: +### Adicione o Middleware a uma Rota + +Isso é válido para ambos os modelos. Você pode adicionar o middleware cookie-parser a uma rota específica. + +```typescript +@Get("get-cookie", cookieParser()) +getCookie(){}; +``` + +Vamos criar uma rota para definir um cookie com um UUID aleatório como valor, que expira em 1 hora e é acessível apenas via HTTP: ```typescript @httpGet("set-cookie") setCookie(@response() res: Response) { res.cookie("authToken", randomUUID(), { - maxAge: 60 * 60 * 1000, // 1 hora + maxAge: 60 * 60 * 1000, // 1 hour httpOnly: true, }); return res.send("Cookie set!"); } ``` -Obter um cookie: +Crie uma rota para obter o valor do cookie: ```typescript @httpGet("get-cookie") @@ -89,18 +91,60 @@ getCookie(@cookies() cookieInfo: string, @response() res: Response) { ``` :::tip -Note que estamos usando o decorator `@cookies()` para obter as informações do cookie. Este decorator é fornecido pelo inversify-express-utils. +`@cookies()` é um decorador auxiliar para obter todos os cookies da requisição. Você também pode usar `@cookies('cookieName')` para obter um cookie específico. ::: +## Quando Usar Cookies + +Os cookies servem a vários propósitos primários: + +1. Gerenciamento de sessão: Os cookies são frequentemente usados para lidar com sessões de usuário. Por exemplo, quando você faz login em um site, um cookie é definido para lembrar seu estado de login. Assim, enquanto você navega pelo site, você permanece logado. + +2. Personalização: Os cookies podem armazenar preferências do usuário para personalizar a experiência do usuário no site. Por exemplo, cookies podem armazenar informações sobre o idioma preferido do usuário, tema ou outras configurações. + +3. Rastreamento: Alguns cookies rastreiam o comportamento do usuário no site ao longo do tempo. Esses são frequentemente usados por ferramentas de análise de terceiros para entender o comportamento do usuário e otimizar o site de acordo. Anunciantes também usam cookies de rastreamento para exibir anúncios direcionados com base na atividade do usuário. + +4. Segurança: Os cookies podem ser usados para suportar funções seguras do site. Por exemplo, um cookie pode ser usado para lembrar que um usuário se autenticou em um site para que o servidor saiba que o usuário já forneceu credenciais de login válidas. + +Também é importante notar que existem diferentes tipos de cookies - cookies de sessão, que expiram quando a sessão do navegador termina, e cookies persistentes, que permanecem no dispositivo do usuário por um período de tempo definido ou até que sejam explicitamente excluídos. + +:::caution USANDO COOKIE PARA RASTREAMENTO +Tenha em mente que o uso de cookies, especialmente para rastreamento e personalização, levantou preocupações com a privacidade, levando a regulamentações como o GDPR na Europa e o CCPA na Califórnia que exigem que os sites divulguem seu uso de cookies e obtenham o consentimento do usuário. +::: + +## Pacote cookie-parser + +- Facilidade de Uso: o cookie-parser torna muito fácil ler valores de cookies, que são frequentemente usados para rastrear sessões de usuários, personalização e gerenciamento de aplicações com estado. Sem esta biblioteca, você teria que analisar manualmente o cabeçalho do Cookie e lidar com as nuances da formatação de cookies. + +- Cookies Assinados: O pacote também suporta cookies assinados, que são uma maneira de verificar a integridade dos cookies (ou seja, se eles foram adulterados). Esta é uma funcionalidade importante para garantir a segurança das informações sensíveis armazenadas nos cookies. + +## O que considerar ao usar o cookie-parser + +- Sobrecarga: Embora não seja uma biblioteca pesada, usar o cookie-parser adiciona um pouco de sobrecarga a cada requisição, pois ele analisa todos os cookies, independentemente de serem usados no manipulador de rota. + +- Estado: Os cookies, por natureza, tornam uma aplicação com estado. Ao escalar uma aplicação, o estado pode ser problemático. Portanto, métodos de autenticação alternativos sem estado, como tokens, podem ser preferíveis em uma arquitetura de microserviços. + +## Quando usar + +Decidir quando usar o cookie-parser depende em grande parte das necessidades de sua aplicação. Se sua aplicação web requer gerenciamento de estado e você escolheu fazer isso por meio de cookies, o cookie-parser pode facilitar sua vida e tornar sua aplicação mais segura com cookies assinados. + +No entanto, se seu site tem um tráfego pesado, a sobrecarga pode se tornar uma preocupação. Se sua arquitetura é baseada em serviços sem estado (comum em arquiteturas de microserviços), você pode querer evitar cookies e optar por outros métodos de manter o estado, como JWTs (JSON Web Tokens). + +:::info +Caso você esteja lidando com um site de alto tráfego, considere alternativas como sessões armazenadas em um banco de dados, JWTs, ou tokens armazenados em cabeçalhos HTTP. Além disso, usar um balanceador de carga para distribuir o tráfego e módulos de armazenamento de sessão para manter dados de sessão em vários servidores pode ajudar a gerenciar alto tráfego e dados com estado. +::: + +Assim como antes, a melhor abordagem geralmente envolve combinar várias técnicas, adaptadas às necessidades específicas de sua aplicação. Testar e monitorar sua aplicação sob condições realistas pode ajudar a orientar seu processo de tomada de decisão. + --- ## Apoie o projeto ExpressoTS é um projeto de código aberto licenciado sob o MIT. É um projeto independente com desenvolvimento contínuo possibilitado graças ao seu suporte. Se você deseja ajudar, por favor considere: -- Se tornar um **[Sponsor no GitHub](https://github.com/sponsors/expressots)** -- Siga a **[organização](https://github.com/expressots)** no GitHub e de um Star ⭐ no projeto -- Subscreva no nosso canal na Twitch: **[Richard Zampieri](https://www.twitch.tv/richardzampieri)** -- Entre no nosso **[Discord](https://discord.com/invite/PyPJfGK)** -- Contribua submetendo **[issues e pull requests](https://github.com/expressots/expressots/issues/new/choose)** -- Compartilhe o projeto com seus amigos e colegas \ No newline at end of file +- Se tornar um **[Sponsor no GitHub](https://github.com/sponsors/expressots)** +- Siga a **[organização](https://github.com/expressots)** no GitHub e de um Star ⭐ no projeto +- Subscreva no nosso canal na Twitch: **[Richard Zampieri](https://www.twitch.tv/richardzampieri)** +- Entre no nosso **[Discord](https://discord.com/invite/PyPJfGK)** +- Contribua submetendo **[issues e pull requests](https://github.com/expressots/expressots/issues/new/choose)** +- Compartilhe o projeto com seus amigos e colegas