Update of documenation

This commit is contained in:
Andrey Sobolev
2025-10-01 11:00:39 +07:00
parent 602ca39606
commit 779e40e9b2
4 changed files with 552 additions and 23 deletions
+41
View File
@@ -0,0 +1,41 @@
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
### Added
- Comprehensive documentation and examples
- GitHub community health files (CONTRIBUTING.md, SECURITY.md)
- Issue and PR templates
## [0.7.9] - 2025-10-01
### Added
- Initial public release
- Core network implementation with distributed architecture
- ZeroMQ-based RPC communication layer
- Client libraries for network interaction
- Server implementation with multi-client support
- High availability support with stateless containers
- Automatic failover and health monitoring
- Multi-tenant container management
- Comprehensive test suite
- Docker deployment support
- Full documentation and examples
### Features
- Distributed load balancing across multiple agents
- Container lifecycle management with reference counting
- Event broadcasting capabilities
- Request/response communication patterns
- Automatic reconnection and retry logic
- Configurable timeouts for different environments
- Label-based container discovery
- Orphaned container detection and cleanup
[Unreleased]: https://github.com/hcengineering/huly.net/compare/v0.7.9...HEAD
[0.7.9]: https://github.com/hcengineering/huly.net/releases/tag/v0.7.9
+325
View File
@@ -0,0 +1,325 @@
# Contributing to Huly Virtual Network
First off, thank you for considering contributing to Huly Virtual Network! It's people like you that make this project such a great tool.
## Table of Contents
- [Code of Conduct](#code-of-conduct)
- [How Can I Contribute?](#how-can-i-contribute)
- [Development Setup](#development-setup)
- [Pull Request Process](#pull-request-process)
- [Coding Standards](#coding-standards)
- [Testing Guidelines](#testing-guidelines)
- [Commit Message Guidelines](#commit-message-guidelines)
## Code of Conduct
This project and everyone participating in it is governed by our commitment to providing a welcoming and inspiring community for all. Please be respectful and constructive in your interactions.
## How Can I Contribute?
### Reporting Bugs
Before creating bug reports, please check the existing issues to avoid duplicates. When you create a bug report, include as many details as possible:
- **Use a clear and descriptive title**
- **Describe the exact steps to reproduce the problem**
- **Provide specific examples** (code snippets, test cases)
- **Describe the behavior you observed** and what you expected
- **Include logs and error messages**
- **Specify your environment** (Node.js version, OS, etc.)
### Suggesting Enhancements
Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion:
- **Use a clear and descriptive title**
- **Provide a detailed description** of the suggested enhancement
- **Explain why this enhancement would be useful**
- **List any alternatives you've considered**
### Pull Requests
We actively welcome your pull requests:
1. Fork the repo and create your branch from `main`
2. If you've added code that should be tested, add tests
3. If you've changed APIs, update the documentation
4. Ensure the test suite passes
5. Make sure your code follows the existing style
6. Issue your pull request!
## Development Setup
### Prerequisites
- **Node.js**: 22.0.0 or higher
- **PNPM**: 10.15.1 or higher (installed automatically via Rush)
- **ZeroMQ**: Native dependencies (libzmq)
### Initial Setup
```bash
# Clone your fork
git clone https://github.com/YOUR_USERNAME/huly.net.git
cd huly.net
# Install dependencies
node common/scripts/install-run-rush.js install
# Build all packages
node common/scripts/install-run-rush.js build
```
### Project Structure
```
huly.net/
├── packages/
│ ├── core/ # Core network implementation
│ ├── backrpc/ # ZeroMQ RPC layer
│ ├── client/ # Client libraries
│ └── server/ # Server implementation
├── pods/
│ └── network-pod/ # Docker deployment
├── tests/ # Integration tests
├── examples/ # Example code
└── docs/ # Documentation
```
### Development Workflow
```bash
# Run tests
node common/scripts/install-run-rush.js test
# Run tests for a specific package
cd packages/core && npm test
# Build with watch mode (during development)
node common/scripts/install-run-rush.js build:watch
# Format code
node common/scripts/install-run-rush.js format
# Validate TypeScript
node common/scripts/install-run-rush.js validate
```
## Pull Request Process
1. **Update Documentation**: Ensure any new features or changes are documented
2. **Add Tests**: Include tests for new functionality
3. **Update CHANGELOG**: Add your changes to the appropriate package CHANGELOG.md
4. **Pass CI**: Ensure all tests pass in CI
5. **Request Review**: Tag relevant maintainers for review
6. **Sign Commits**: Use `git commit -s` to sign off on your commits
### PR Title Format
Use descriptive PR titles that follow this format:
```
[Package] Brief description of changes
Examples:
[core] Add support for custom container timeouts
[client] Fix reconnection logic for dropped connections
[docs] Update production deployment guide
```
## Coding Standards
### TypeScript Style
- **Use TypeScript strict mode**: All code must pass strict type checking
- **Prefer interfaces over types** for object shapes
- **Use async/await** over raw Promises
- **Document public APIs** with JSDoc comments
- **Use descriptive variable names**: No single-letter variables except in loops
### Code Organization
```typescript
// 1. Imports (grouped: external, internal, types)
import { EventEmitter } from 'events'
import { NetworkImpl } from '../network'
import type { Container, ContainerUuid } from '../types'
// 2. Types and interfaces
interface MyOptions {
timeout: number
}
// 3. Class implementation
export class MyClass {
// Private fields first
private readonly config: MyOptions
// Constructor
constructor(options: MyOptions) {
this.config = options
}
// Public methods
async doSomething(): Promise<void> {
// Implementation
}
// Private methods
private helper(): void {
// Implementation
}
}
```
### Error Handling
- **Always handle errors explicitly**: No silent failures
- **Use typed errors**: Create custom error classes when needed
- **Provide context**: Include relevant information in error messages
```typescript
// Good
try {
await operation()
} catch (error: any) {
throw new Error(`Failed to perform operation: ${error.message}`)
}
// Bad
try {
await operation()
} catch (error) {
// Silent failure
}
```
## Testing Guidelines
### Test Structure
```typescript
describe('ComponentName', () => {
describe('methodName', () => {
it('should behave correctly under normal conditions', async () => {
// Arrange
const component = new ComponentName()
// Act
const result = await component.methodName()
// Assert
expect(result).toBe(expected)
})
it('should handle error conditions', async () => {
// Test error cases
})
})
})
```
### Test Coverage
- **Aim for 80%+ coverage**: All new code should have tests
- **Test edge cases**: Don't just test the happy path
- **Test error conditions**: Verify error handling works correctly
- **Integration tests**: Add tests that verify component interaction
### Running Tests
```bash
# Run all tests
node common/scripts/install-run-rush.js test
# Run tests for a specific package
cd packages/core
npm test
# Run tests in watch mode
npm test -- --watch
# Generate coverage report
npm test -- --coverage
```
## Commit Message Guidelines
We follow conventional commits for clear git history:
### Format
```
<type>(<scope>): <subject>
<body>
<footer>
```
### Types
- **feat**: A new feature
- **fix**: A bug fix
- **docs**: Documentation only changes
- **style**: Code style changes (formatting, missing semi-colons, etc.)
- **refactor**: Code changes that neither fix bugs nor add features
- **perf**: Performance improvements
- **test**: Adding or updating tests
- **chore**: Maintenance tasks, dependency updates
### Examples
```
feat(core): add support for custom container timeouts
Adds a new timeout parameter to the Network constructor that allows
customizing how long containers stay alive when unreferenced.
Closes #123
---
fix(client): prevent memory leak in connection pool
The connection pool was not properly cleaning up closed connections,
leading to memory growth over time.
---
docs(readme): update quick start guide
Add more detailed examples for common use cases.
```
### Signing Commits
All commits must be signed off:
```bash
git commit -s -m "Your commit message"
```
This adds a "Signed-off-by" line indicating you agree to the [Developer Certificate of Origin](https://developercertificate.org/).
## Documentation
- **Update README.md** for significant changes
- **Add JSDoc comments** for public APIs
- **Create examples** for new features
- **Update relevant docs/** files
## Questions?
- **GitHub Issues**: For bugs and feature requests
- **GitHub Discussions**: For questions and general discussion
- **Documentation**: Check the [docs](docs/) directory
## License
By contributing, you agree that your contributions will be licensed under the Eclipse Public License 2.0.
---
Thank you for contributing to Huly Virtual Network! 🚀
+150 -23
View File
@@ -1,6 +1,37 @@
# Huly Virtual Network
<div align="center">
A distributed, scalable virtual network architecture that enables fault-tolerant communication across distributed containers and agents.
# 🌐 Huly Virtual Network
[![License: EPL 2.0](https://img.shields.io/badge/License-EPL%202.0-blue.svg)](https://opensource.org/licenses/EPL-2.0)
[![npm version](https://img.shields.io/npm/v/@hcengineering/network-core.svg)](https://www.npmjs.com/package/@hcengineering/network-core)
[![CI](https://github.com/hcengineering/huly.net/workflows/CI/badge.svg)](https://github.com/hcengineering/huly.net/actions)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.8+-3178c6.svg)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-22+-339933.svg)](https://nodejs.org/)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
**A distributed, scalable virtual network architecture that enables fault-tolerant communication across distributed containers and agents.**
Build enterprise-grade distributed systems with automatic service discovery, high availability, and zero-configuration deployment.
[Features](#-why-build-your-product-on-huly-network) • [Quick Start](#-getting-started) • [Documentation](#-documentation) • [Examples](#-examples) • [API Reference](#-api-reference) • [Contributing](#-contributing)
</div>
---
## 📋 Table of Contents
- [Why Huly Network?](#-why-build-your-product-on-huly-network)
- [Overview](#-overview)
- [Architecture](#-architecture)
- [Packages](#-packages)
- [Quick Start](#-getting-started)
- [Examples](#-examples)
- [Documentation](#-documentation)
- [API Reference](#-api-reference)
- [Testing](#-testing)
- [Contributing](#-contributing)
- [License](#-license)
## 🌟 Why Build Your Product on Huly Network?
@@ -307,7 +338,33 @@ async function main() {
main().catch(console.error)
```
## 📚 Comprehensive Examples
## 📚 Documentation
### 📖 Guides
- **[Core Concepts](docs/CORE_CONCEPTS.md)** - Understand the architecture and design principles
- **[Quick Start Guide](docs/QUICKSTART.md)** - Get up and running in minutes
- **[Production Deployment](docs/PRODUCTION_DEPLOYMENT.md)** - Deploy to production environments
- **[Container Development](docs/CONTAINER_DEVELOPMENT.md)** - Build custom containers
- **[High Availability Setup](docs/QUICKSTART_HA.md)** - Configure HA with stateless containers
- **[HA Stateless Containers](docs/HA_STATELESS_CONTAINERS.md)** - Deep dive into HA patterns
- **[Multi-Tenant Architecture](docs/MULTI_TENANT.md)** - Implement multi-tenancy
### 🎯 Examples
All examples are available in the [`examples/`](examples/) directory:
1. **[Basic Request/Response](examples/01-basic-container-request-response.ts)** - Simple container communication
2. **[Event Broadcasting](examples/02-event-broadcasting.ts)** - Real-time event distribution
3. **[Multi-Tenant Setup](examples/03-multi-tenant.ts)** - Per-tenant container isolation
4. **[Production Setup](examples/04-complete-production-setup.ts)** - Complete production configuration
5. **[Error Handling & Retry](examples/05-error-handling-retry.ts)** - Robust error handling patterns
6. **[Custom Timeouts](examples/custom-timeout-example.ts)** - Environment-specific timeouts
7. **[HA Stateless Containers](examples/ha-stateless-container-example.ts)** - Automatic failover
See the [Examples README](examples/README.md) for detailed explanations and usage instructions.
## Detailed Example Walkthroughs
### Example 1: Basic Container with Request/Response
@@ -1055,7 +1112,7 @@ process.on('SIGINT', async () => {
})
```
For more examples, see the `examples/` directory in the repository.
---
## 📚 API Reference
@@ -1193,34 +1250,104 @@ node common/scripts/install-run-rush.js build:watch
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Make your changes and add tests
4. Install dependencies: `node common/scripts/install-run-rush.js install`
5. Ensure all tests pass: `node common/scripts/install-run-rush.js test`
6. Format code: `node common/scripts/install-run-rush.js format`
7. Build project: `node common/scripts/install-run-rush.js build`
8. Commit changes: `git commit -s -m 'Add amazing feature'`
9. Push to branch: `git push origin feature/amazing-feature`
10. Open a Pull Request
We love contributions! Huly Virtual Network is open source and we welcome contributions of all kinds:
### Development Setup
- 🐛 **Bug Reports**: Found a bug? [Open an issue](https://github.com/hcengineering/huly.net/issues/new?template=bug_report.md)
-**Feature Requests**: Have an idea? [Request a feature](https://github.com/hcengineering/huly.net/issues/new?template=feature_request.md)
- 📖 **Documentation**: Improve our docs, add examples, or fix typos
- 💻 **Code**: Submit pull requests with bug fixes or new features
-**Questions**: [Ask questions](https://github.com/hcengineering/huly.net/issues/new?template=question.md) to help improve our documentation
The project uses Rush.js for monorepo management:
Please read our [Contributing Guide](CONTRIBUTING.md) for details on our development process, coding standards, and how to submit pull requests.
- All packages share common build configuration
- Dependencies are managed at the workspace level
- Incremental builds and caching for faster development
### Quick Contribution Guide
1. **Fork** the repository
2. **Create** a feature branch: `git checkout -b feature/amazing-feature`
3. **Make** your changes and add tests
4. **Run** tests: `node common/scripts/install-run-rush.js test`
5. **Format** code: `node common/scripts/install-run-rush.js format`
6. **Commit** with sign-off: `git commit -s -m 'Add amazing feature'`
7. **Push** to your fork: `git push origin feature/amazing-feature`
8. **Open** a Pull Request
### Development Commands
```bash
# Install dependencies
node common/scripts/install-run-rush.js install
# Build all packages
node common/scripts/install-run-rush.js build
# Run tests
node common/scripts/install-run-rush.js test
# Format code
node common/scripts/install-run-rush.js format
# Build with watch mode
node common/scripts/install-run-rush.js build:watch
```
See our [Contributing Guide](CONTRIBUTING.md) for more detailed information.
## 📄 License
This project is licensed under the Eclipse Public License 2.0 - see the [LICENSE](LICENSE) file for details.
This project is licensed under the **Eclipse Public License 2.0** - see the [LICENSE](LICENSE) file for details.
The EPL-2.0 is a business-friendly open source license that allows you to:
- ✅ Use the software commercially
- ✅ Modify the software
- ✅ Distribute the software
- ✅ Use the software privately
- ✅ Include it in proprietary software
Learn more about [EPL-2.0](https://www.eclipse.org/legal/epl-2.0/).
## 🔒 Security
Security is a top priority. If you discover a security vulnerability, please follow our [Security Policy](SECURITY.md) for responsible disclosure.
## 🙏 Acknowledgments
- Built with [ZeroMQ](https://zeromq.org/) for high-performance messaging
- Managed with [Rush.js](https://rushjs.io/) for monorepo orchestration
- Part of the [Huly Platform](https://github.com/hcengineering/platform) ecosystem
## 📬 Contact & Support
- **Issues**: [GitHub Issues](https://github.com/hcengineering/huly.net/issues)
- **Discussions**: [GitHub Discussions](https://github.com/hcengineering/huly.net/discussions)
- **Website**: [huly.io](https://huly.io)
- **Twitter**: [@huly_platform](https://twitter.com/huly_platform)
## 🗺️ Roadmap
See our [project roadmap](https://github.com/hcengineering/huly.net/projects) for upcoming features and improvements.
## 📊 Project Status
This project is actively maintained and used in production by the Huly Platform. We welcome contributions and feedback!
## ⭐ Star History
If you find this project useful, please consider giving it a star! It helps others discover the project.
[![Star History Chart](https://api.star-history.com/svg?repos=hcengineering/huly.net&type=Date)](https://star-history.com/#hcengineering/huly.net&Date)
## 🔗 Related Projects
- [Huly Platform](https://github.com/hcengineering/platform) - The main Huly platform
- [ZeroMQ](https://zeromq.org/) - High-performance messaging library
- **[Huly Platform](https://github.com/hcengineering/platform)** - The main Huly platform that uses this network
- **[ZeroMQ](https://zeromq.org/)** - High-performance asynchronous messaging library
- **[Rush.js](https://rushjs.io/)** - Scalable monorepo build orchestrator
---
**Note**: This is a foundational networking library for the Huly ecosystem. For application-level documentation, please refer to the main Huly platform repository.
<div align="center">
**Built with ❤️ by the Huly Platform team**
[⬆ back to top](#-huly-virtual-network)
</div>
+36
View File
@@ -108,6 +108,42 @@ Introduce streaming capabilities to enable efficient partial data transfer from
**Use Cases**:
- **Large Response Payloads**: Stream large datasets without loading everything in memory
### 6. Security and External Client/Agent Support
Enable secure external access to the Huly Network Server Hub, allowing trusted clients and agents outside the private installation to consume services safely.
**Key Features**:
- **Authentication & Authorization**: Implement robust token-based authentication (JWT, API keys) for external clients
- **TLS/SSL Encryption**: Enforce encrypted connections for all external communication
- **Rate Limiting**: Apply granular rate limits per client/agent to prevent abuse
- **Access Control Lists (ACLs)**: Fine-grained permissions for external clients to access specific services
- **Audit Logging**: Comprehensive logging of external access attempts and activities
**Security Considerations**:
- Network isolation between internal and external traffic
- DDoS protection and request filtering
- Certificate management and rotation
- Secure credential storage and rotation policies
- IP whitelisting/blacklisting capabilities
**Use Cases**:
- Third-party integrations accessing Huly services
- Remote monitoring and management agents
- External webhooks and event consumers
- Partner applications requiring controlled access
- Mobile/desktop clients connecting from public networks
**Benefits**:
- Secure extension of Huly Network beyond internal networks
- Controlled exposure of services to external consumers
- Enhanced flexibility for hybrid deployment scenarios
- Support for distributed teams and remote workers
- **Real-time Data Processing**: Push incremental results as they become available
## Other Important Tasks