hightjs 0.3.2 → 0.3.4

package/docs/config.md

@@ -0,0 +1,201 @@
+# HightJS Configuration (hightjs.config.ts)
+
+O HightJS permite que você personalize as configurações do servidor através de um arquivo `hightjs.config.ts` (ou `.js`) na raiz do seu projeto.
+
+## 📝 Estrutura Básica
+
+### Opção 1: Função de Configuração (Recomendado)
+
+```typescript
+import type { HightConfig, HightConfigFunction } from 'hightjs';
+
+const hightConfig: HightConfigFunction = (phase, { defaultConfig }) => {
+    const config: HightConfig = {
+        maxHeadersCount: 100,
+        headersTimeout: 60000,
+        requestTimeout: 30000,
+        serverTimeout: 35000,
+        individualRequestTimeout: 30000,
+        maxUrlLength: 2048,
+    };
+
+    // Personalize baseado no ambiente
+    if (phase === 'development') {
+        config.requestTimeout = 60000;
+        config.individualRequestTimeout = 60000;
+    }
+
+    if (phase === 'production') {
+        config.maxHeadersCount = 50;
+        config.maxUrlLength = 1024;
+    }
+
+    return config;
+};
+
+export default hightConfig;
+```
+
+### Opção 2: Objeto Estático
+
+```typescript
+import type { HightConfig } from 'hightjs';
+
+const config: HightConfig = {
+    maxHeadersCount: 100,
+    headersTimeout: 60000,
+    requestTimeout: 30000,
+    serverTimeout: 35000,
+    individualRequestTimeout: 30000,
+    maxUrlLength: 2048,
+};
+
+export default config;
+```
+
+## ⚙️ Configurações Disponíveis
+
+| Propriedade | Tipo | Padrão | Descrição |
+|------------|------|--------|-----------|
+| `maxHeadersCount` | `number` | `100` | Número máximo de headers HTTP permitidos por requisição |
+| `headersTimeout` | `number` | `60000` | Timeout em ms para receber os headers HTTP |
+| `requestTimeout` | `number` | `30000` | Timeout em ms para uma requisição completa |
+| `serverTimeout` | `number` | `35000` | Timeout geral do servidor em ms |
+| `individualRequestTimeout` | `number` | `30000` | Timeout por requisição individual em ms |
+| `maxUrlLength` | `number` | `2048` | Tamanho máximo da URL em caracteres |
+
+## 🎯 Casos de Uso
+
+### Aumentar Timeouts para Debugging
+
+```typescript
+const config: HightConfig = {
+    requestTimeout: 120000, // 2 minutos
+    individualRequestTimeout: 120000,
+};
+```
+
+### Aumentar Limites para APIs com Muitos Headers
+
+```typescript
+const config: HightConfig = {
+    maxHeadersCount: 200, // Dobro do padrão
+};
+```
+
+### Configuração Rigorosa para Produção
+
+```typescript
+const hightConfig: HightConfigFunction = (phase) => {
+    if (phase === 'production') {
+        return {
+            maxHeadersCount: 50,
+            maxUrlLength: 1024,
+            requestTimeout: 15000, // Mais restritivo
+            individualRequestTimeout: 15000,
+        };
+    }
+    
+    // Valores padrão para desenvolvimento
+    return {};
+};
+```
+
+### Suporte a URLs Muito Longas
+
+```typescript
+const config: HightConfig = {
+    maxUrlLength: 4096, // Dobro do padrão
+};
+```
+
+## 🔄 Hot Reload
+
+Em modo de desenvolvimento (`dev: true`), o arquivo de configuração é recarregado automaticamente quando modificado, permitindo ajustes sem reiniciar o servidor.
+
+## 📦 TypeScript vs JavaScript
+
+### TypeScript (Recomendado)
+- Arquivo: `hightjs.config.ts`
+- Benefícios: Autocomplete, validação de tipos, detecção de erros
+
+### JavaScript
+- Arquivo: `hightjs.config.js`
+- Use JSDoc para ter intellisense:
+
+```javascript
+/**
+ * @type {import('hightjs').HightConfigFunction}
+ */
+const hightConfig = (phase, { defaultConfig }) => {
+    /** @type {import('hightjs').HightConfig} */
+    const config = {
+        maxHeadersCount: 100,
+    };
+    
+    return config;
+};
+
+module.exports = hightConfig;
+```
+
+## 🚀 Exemplo Completo
+
+```typescript
+import type { HightConfig, HightConfigFunction } from 'hightjs';
+
+const hightConfig: HightConfigFunction = (phase, { defaultConfig }) => {
+    // Começa com valores padrão
+    const config: HightConfig = { ...defaultConfig };
+
+    // Configurações comuns
+    config.maxHeadersCount = 150;
+
+    // Ajustes por ambiente
+    if (phase === 'development') {
+        // Timeouts maiores para debugging
+        config.requestTimeout = 120000;
+        config.individualRequestTimeout = 120000;
+        
+        // URLs longas para testes
+        config.maxUrlLength = 4096;
+    } else if (phase === 'production') {
+        // Mais restritivo em produção
+        config.maxHeadersCount = 50;
+        config.maxUrlLength = 1024;
+        config.requestTimeout = 20000;
+        config.individualRequestTimeout = 20000;
+        
+        // Timeouts mais curtos para headers
+        config.headersTimeout = 30000;
+        config.serverTimeout = 25000;
+    }
+
+    return config;
+};
+
+export default hightConfig;
+```
+
+## 📍 Localização do Arquivo
+
+O arquivo `hightjs.config.ts` (ou `.js`) deve estar na **raiz do seu projeto**, no mesmo nível do `package.json`.
+
+```
+seu-projeto/
+├── hightjs.config.ts  ← Aqui
+├── package.json
+├── tsconfig.json
+└── src/
+    └── web/
+        └── ...
+```
+
+## ⚠️ Notas Importantes
+
+1. **Prioridade**: `.ts` tem prioridade sobre `.js` se ambos existirem
+2. **Fallback**: Se o arquivo não existir, valores padrão serão usados
+3. **Validação**: Valores inválidos serão ignorados e substituídos pelos padrões
+4. **Performance**: Use valores apropriados para evitar timeouts desnecessários ou aberturas de segurança
+5. **Segurança**: Não exponha valores muito altos em produção (ex: `maxUrlLength` muito grande pode facilitar ataques DoS)
+

package/example/hightjs.config.ts

@@ -0,0 +1,81 @@
+import type { HightConfig, HightConfigFunction } from 'hightjs';
+
+/**
+ * HightJS Configuration File
+ *
+ * This file allows you to customize server settings for your HightJS application.
+ * You can export either a static configuration object or a function that returns the configuration.
+ *
+ * In a real project, you would import from 'hightjs' instead:
+ * import type { HightConfig, HightConfigFunction } from 'hightjs';
+ */
+const hightConfig: HightConfigFunction = (phase, { defaultConfig }) => {
+    const config: HightConfig = {
+        /**
+         * Maximum number of HTTP headers allowed per request
+         * Default: 100
+         * Increase this if you need to support requests with many headers
+         */
+        maxHeadersCount: 100,
+
+        /**
+         * Timeout in milliseconds for receiving HTTP headers
+         * Default: 60000 (60 seconds)
+         */
+        headersTimeout: 60000,
+
+        /**
+         * Timeout in milliseconds for a complete request
+         * Default: 30000 (30 seconds)
+         */
+        requestTimeout: 30000,
+
+        /**
+         * General server timeout in milliseconds
+         * Default: 35000 (35 seconds)
+         */
+        serverTimeout: 35000,
+
+        /**
+         * Timeout per individual request in milliseconds
+         * Default: 30000 (30 seconds)
+         */
+        individualRequestTimeout: 30000,
+
+        /**
+         * Maximum URL length in characters
+         * Default: 2048
+         */
+        maxUrlLength: 2048,
+    };
+
+    // You can customize settings based on the phase
+    if (phase === 'development') {
+        // In development, you might want longer timeouts for debugging
+        config.requestTimeout = 60000;
+        config.individualRequestTimeout = 60000;
+    }
+
+    if (phase === 'production') {
+        // In production, you might want stricter limits
+        config.maxHeadersCount = 50;
+        config.maxUrlLength = 1024;
+    }
+
+    return config;
+};
+
+export default hightConfig;
+
+// You can also export a static object instead of a function:
+// const staticConfig: HightConfig = {
+//     maxHeadersCount: 100,
+//     headersTimeout: 60000,
+//     requestTimeout: 30000,
+//     serverTimeout: 35000,
+//     individualRequestTimeout: 30000,
+//     maxUrlLength: 2048,
+// };
+//
+// export default staticConfig;
+