Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
268 lines (191 loc) · 5.68 KB

CONTRIBUTING.md

File metadata and controls

268 lines (191 loc) · 5.68 KB

Contributing to Node-Go Reverse Proxy

Thank you for your interest in contributing to the Node-Go Reverse Proxy project! This document provides guidelines and suggestions for contributing.

How to Contribute

🐛 Bug Reports

When filing bug reports, please include:

  • Clear description of the issue
  • Steps to reproduce the problem
  • Expected behavior vs actual behavior
  • Environment details (Node.js version, OS, etc.)
  • Code examples that demonstrate the issue

✨ Feature Requests

For feature requests, please:

  • Search existing issues first to avoid duplicates
  • Describe the use case and why it would be valuable
  • Provide examples of how the feature would be used
  • Consider backward compatibility implications

🔧 Code Contributions

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes following our coding standards
  4. Add tests for new functionality
  5. Update documentation if needed
  6. Commit with clear messages
  7. Push to your fork (git push origin feature/amazing-feature)
  8. Open a Pull Request

Development Setup

Prerequisites

  • Node.js 16+ and npm
  • Go 1.19+ (for testing with Go services)
  • Git

Local Development

# Clone your fork
git clone https://github.com/your-username/node-go-proxy.git
cd node-go-proxy

# Install dependencies
npm install

# Run tests
npm test

# Start example Go server for testing
cd examples && go run server.go

Coding Standards

TypeScript/JavaScript

  • Use TypeScript for all new code
  • Follow ESLint and Prettier configurations
  • Use meaningful variable names
  • Add JSDoc comments for public functions
  • Prefer async/await over Promises
/**
 * Proxies HTTP requests to a target server
 * @param options - Proxy configuration options
 * @param callback - Optional callback for request/response processing
 */
export const expressMiddlewareProxy = (
  options: ProxyOptions,
  callback?: ProxyCallback
) => {
  // Implementation
};

Testing

  • Write unit tests for all new functions
  • Write integration tests for middleware behavior
  • Use Jest for testing framework
  • Aim for 80%+ test coverage
describe('expressMiddlewareProxy', () => {
  it('should proxy GET requests correctly', async () => {
    // Test implementation
  });

  it('should handle file uploads', async () => {
    // Test implementation
  });
});

Documentation

README Updates

When adding features, update the README with:

  • Usage examples
  • API documentation
  • Configuration options

Code Comments

  • Use JSDoc for function documentation
  • Add inline comments for complex logic
  • Explain why, not just what

Performance Considerations

Memory Usage

  • Avoid memory leaks in long-running processes
  • Stream large responses when possible
  • Implement size limits for request/response data

Error Handling

  • Handle all error cases gracefully
  • Provide meaningful error messages
  • Log errors appropriately
try {
  await processRequest();
} catch (error) {
  console.error('Request processing failed:', error.message);
  res.status(500).json({ error: 'Internal server error' });
}

Release Process

Version Bumping

We follow Semantic Versioning:

  • Patch (1.0.x): Bug fixes
  • Minor (1.x.0): New features (backward compatible)
  • Major (x.0.0): Breaking changes

Changelog

Update CHANGELOG.md with:

  • Added features
  • Changed behavior
  • Deprecated functionality
  • Removed features
  • Fixed bugs
  • Security improvements

Testing Guidelines

Test Categories

  1. Unit Tests: Test individual functions
  2. Integration Tests: Test middleware with Express
  3. End-to-End Tests: Test with real Go services

Test Structure

describe('Feature Name', () => {
  beforeEach(() => {
    // Setup
  });

  afterEach(() => {
    // Cleanup
  });

  describe('when condition', () => {
    it('should behave correctly', () => {
      // Test
    });
  });
});

Common Issues & Solutions

Double Response Writing

Problem: Writing to response stream multiple times

Solution: Buffer data first, then write once

// ❌ Wrong
pres.on('data', chunk => {
  chunks.push(chunk);
  ores.write(chunk); // Don't do this with callbacks
});

// ✅ Correct
pres.on('data', chunk => {
  chunks.push(chunk); // Just buffer
});

Memory Leaks

Problem: Not cleaning up event listeners

Solution: Remove listeners and handle errors

const cleanup = () => {
  req.removeAllListeners();
  res.removeAllListeners();
};

req.on('error', cleanup);
res.on('error', cleanup);

Security Guidelines

Input Validation

  • Validate all inputs including headers and paths
  • Sanitize user data before forwarding
  • Implement rate limiting in examples

Headers

  • Don't forward sensitive headers unnecessarily
  • Validate content-type headers
  • Handle authorization properly

Community

Code of Conduct

  • Be respectful and inclusive
  • Help others learn and grow
  • Focus on what's best for the community
  • Welcome newcomers and questions

Getting Help

  • Check documentation first
  • Search existing issues
  • Ask in discussions for general questions
  • File issues for bugs or feature requests

Recognition

Contributors will be recognized in:

  • README.md contributors section
  • Release notes for significant contributions
  • GitHub contributors page

Thank you for helping make Node-Go Reverse Proxy better! 🚀