{"id":31802099,"url":"https://github.com/cloud-shuttle/cloudshuttle-shared","last_synced_at":"2025-10-11T00:17:08.177Z","repository":{"id":317451954,"uuid":"1066915850","full_name":"cloud-shuttle/cloudshuttle-shared","owner":"cloud-shuttle","description":null,"archived":false,"fork":false,"pushed_at":"2025-09-30T23:18:29.000Z","size":145,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-01T01:11:36.219Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloud-shuttle.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-30T06:14:48.000Z","updated_at":"2025-09-30T23:16:56.000Z","dependencies_parsed_at":"2025-10-01T01:12:48.472Z","dependency_job_id":"46935d1c-8d39-4b6e-8482-7737dda9a586","html_url":"https://github.com/cloud-shuttle/cloudshuttle-shared","commit_stats":null,"previous_names":["cloud-shuttle/cloudshuttle-shared"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/cloud-shuttle/cloudshuttle-shared","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-shuttle%2Fcloudshuttle-shared","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-shuttle%2Fcloudshuttle-shared/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-shuttle%2Fcloudshuttle-shared/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-shuttle%2Fcloudshuttle-shared/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloud-shuttle","download_url":"https://codeload.github.com/cloud-shuttle/cloudshuttle-shared/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-shuttle%2Fcloudshuttle-shared/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279005657,"owners_count":26083941,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-11T00:17:06.318Z","updated_at":"2025-10-11T00:17:08.171Z","avatar_url":"https://github.com/cloud-shuttle.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CloudShuttle Shared Libraries\n\n\u003e Reusable code components that eliminate duplication and ensure consistency across all CloudShuttle services\n\n## Overview\n\nThe `cloudshuttle-shared` repository contains shared libraries and utilities used across all CloudShuttle services. This repository eliminates code duplication, ensures consistency, and provides a centralized location for common functionality.\n\n## 🚀 Quick Start\n\n**New to CloudShuttle shared libraries?** Start here:\n\n📖 **[USAGE_GUIDE.md](USAGE_GUIDE.md)** - Complete guide for using CloudShuttle libraries with Git dependencies and tags\n\n```toml\n[dependencies]\ncloudshuttle-api = { git = \"https://github.com/cloud-shuttle/cloudshuttle-shared.git\", tag = \"v0.4.0\" }\ncloudshuttle-auth = { git = \"https://github.com/cloud-shuttle/cloudshuttle-shared.git\", tag = \"v0.4.0\" }\n```\n\nSee the **[USAGE_GUIDE.md](USAGE_GUIDE.md)** for detailed setup instructions, examples, and troubleshooting.\n\n## Repository Structure\n\n```\ncloudshuttle-shared/\n├── rust/                          # Rust shared libraries\n│   ├── Cargo.toml                # Workspace configuration\n│   └── crates/                   # Individual Rust crates\n│       ├── error-handling/       # Error types and handling\n│       ├── database/            # Database utilities\n│       ├── auth/                # Authentication helpers\n│       ├── observability/       # Logging \u0026 metrics\n│       ├── config/              # Configuration management\n│       ├── api/                 # API utilities\n│       ├── validation/          # Input validation\n│       └── crypto/              # Cryptographic utilities\n├── typescript/                   # TypeScript shared libraries\n│   ├── package.json             # Workspace configuration\n│   └── packages/                # Individual TypeScript packages\n│       ├── components/          # React components\n│       ├── hooks/               # React hooks\n│       ├── types/               # TypeScript types\n│       ├── utils/               # Utility functions\n│       ├── api/                 # API client utilities\n│       └── stores/              # State management\n├── docs/                        # Documentation\n│   ├── rust-libraries.md        # Rust library guide\n│   ├── typescript-libraries.md  # TypeScript library guide\n│   ├── versioning.md            # Versioning strategy\n│   └── contributing.md          # Contribution guidelines\n├── .github/                     # CI/CD workflows\n│   └── workflows/\n│       ├── ci.yml               # CI pipeline\n│       ├── publish.yml          # Automated publishing\n│       └── security.yml         # Security scanning\n├── scripts/                     # Build and release scripts\n│   ├── build-all.sh            # Build all libraries\n│   ├── test-all.sh             # Test all libraries\n│   └── release.sh              # Automated release\n└── README.md                   # This file\n```\n\n## Rust Libraries\n\n### 1. Error Handling (`cloudshuttle-error-handling`)\n\n**Purpose**: Standardized error types and handling patterns\n\n**Features**:\n- `CloudShuttleError` - Main error enum for all services\n- `ServiceError` trait - Service-specific error handling\n- `ApiError` - HTTP API error responses\n- `DatabaseError` - Database operation errors\n\n**Usage**:\n```rust\nuse cloudshuttle_error_handling::{CloudShuttleError, ServiceError};\n\n// Implement service-specific errors\n#[derive(Debug, thiserror::Error)]\npub struct MyServiceError {\n    message: String,\n}\n\nimpl ServiceError for MyServiceError {\n    fn error_code(\u0026self) -\u003e \u0026'static str { \"MY_SERVICE_ERROR\" }\n    fn http_status(\u0026self) -\u003e http::StatusCode { http::StatusCode::INTERNAL_SERVER_ERROR }\n    fn user_message(\u0026self) -\u003e String { self.message.clone() }\n}\n```\n\n### 2. Database (`cloudshuttle-database`)\n\n**Purpose**: Common database utilities and connection management\n\n**Features**:\n- Connection pooling and management\n- Query builders and helpers\n- Transaction management\n- Migration utilities\n\n### 3. Authentication (`cloudshuttle-auth`)\n\n**Purpose**: JWT handling and authentication utilities\n\n**Features**:\n- JWT token creation and validation\n- Claims structure and management\n- Authentication middleware\n- Key management utilities\n\n### 4. Observability (`cloudshuttle-observability`)\n\n**Purpose**: Logging, metrics, and tracing utilities\n\n**Features**:\n- Structured logging with context\n- Prometheus metrics collection\n- Distributed tracing support\n- Health check utilities\n\n### 5. Configuration (`cloudshuttle-config`)\n\n**Purpose**: Configuration loading and validation\n\n**Features**:\n- Environment-based configuration\n- Validation with detailed error messages\n- Secret management\n- Configuration reloading\n\n### 6. API (`cloudshuttle-api`)\n\n**Purpose**: Common API utilities and response formatting\n\n**Features**:\n- Standardized API responses\n- Pagination support\n- Filtering and sorting utilities\n- Request validation\n\n### 7. Validation (`cloudshuttle-validation`)\n\n**Purpose**: Input validation and sanitization\n\n**Features**:\n- Common validation rules\n- Input sanitization\n- Custom validators\n- Validation error formatting\n\n### 8. Crypto (`cloudshuttle-crypto`)\n\n**Purpose**: Cryptographic utilities for secure operations\n\n**Features**:\n- Password hashing\n- Data encryption/decryption\n- Digital signatures\n- Secure random generation\n\n## TypeScript Libraries\n\n### 1. Components (`@cloudshuttle/components`)\n\n**Purpose**: Reusable React components\n\n**Features**:\n- Button, Input, Modal components\n- Form components\n- Layout components\n- Table and data display components\n\n### 2. Hooks (`@cloudshuttle/hooks`)\n\n**Purpose**: Custom React hooks\n\n**Features**:\n- `useApi` - API call management\n- `useAuth` - Authentication state\n- `useLocalStorage` - Local storage persistence\n- `usePagination` - Pagination logic\n\n### 3. Types (`@cloudshuttle/types`)\n\n**Purpose**: Shared TypeScript type definitions\n\n**Features**:\n- API response types\n- User and tenant types\n- Form and validation types\n- Common utility types\n\n### 4. Utils (`@cloudshuttle/utils`)\n\n**Purpose**: Utility functions\n\n**Features**:\n- Data formatters\n- Date/time utilities\n- String manipulation\n- Array and object helpers\n\n### 5. API (`@cloudshuttle/api`)\n\n**Purpose**: API client utilities\n\n**Features**:\n- HTTP client configuration\n- Request/response interceptors\n- Error handling\n- Authentication headers\n\n### 6. Stores (`@cloudshuttle/stores`)\n\n**Purpose**: State management stores\n\n**Features**:\n- Authentication store\n- User preferences store\n- Notification store\n- Application state stores\n\n## Versioning Strategy\n\n### Semantic Versioning\n```\nMAJOR.MINOR.PATCH\n\nMAJOR: Breaking changes\nMINOR: New features (backward compatible)\nPATCH: Bug fixes (backward compatible)\n```\n\n### Publishing Cadence\n- **Major releases**: Breaking changes, coordinated across services\n- **Minor releases**: New features, monthly\n- **Patch releases**: Bug fixes, as needed\n\n### Dependency Management\n```toml\n# In service Cargo.toml\n[dependencies]\ncloudshuttle-error-handling = \"1.2.3\"\ncloudshuttle-database = \"1.1.0\"\n```\n\n## Development Setup\n\n### Prerequisites\n- **Rust**: 1.75+ with Cargo\n- **Node.js**: 18+ with npm or pnpm\n- **Git**: For repository management\n\n### Local Development\n```bash\n# Clone the repository\ngit clone https://github.com/cloudshuttle/cloudshuttle-shared.git\ncd cloudshuttle-shared\n\n# Rust development\ncd rust\ncargo build\ncargo test\n\n# TypeScript development\ncd ../typescript\npnpm install\npnpm build\npnpm test\n```\n\n### Building All Libraries\n```bash\n# Use the build script\n./scripts/build-all.sh\n\n# Or build manually\ncd rust \u0026\u0026 cargo build --release\ncd ../typescript \u0026\u0026 pnpm build\n```\n\n### Running Tests\n```bash\n# Run all tests\n./scripts/test-all.sh\n\n# Or test individually\ncd rust \u0026\u0026 cargo test\ncd ../typescript \u0026\u0026 pnpm test\n```\n\n## Publishing\n\n### Git-Based Distribution (Private)\nFor security and IP protection, shared libraries are distributed via Git dependencies rather than public registries:\n\n```bash\n# Create and push a version tag\ngit tag v1.2.3\ngit push origin v1.2.3\n\n# CI/CD validates all libraries compile and tests pass\n# Libraries remain private in this GitHub repository\n```\n\n### Usage in Services\n```toml\n# In service Cargo.toml\n[dependencies]\ncloudshuttle-error-handling = { git = \"https://github.com/cloudshuttle/cloudshuttle-shared.git\", tag = \"v1.2.3\" }\ncloudshuttle-database = { git = \"https://github.com/cloudshuttle/cloudshuttle-shared.git\", tag = \"v1.2.3\" }\n```\n\n```json\n// In package.json\n{\n  \"dependencies\": {\n    \"@cloudshuttle/components\": \"github:cloudshuttle/cloudshuttle-shared#v1.2.3\"\n  }\n}\n```\n\n### Security Note\nThese libraries contain authentication, cryptographic, and business logic that must remain private. They are distributed via Git dependencies to maintain security and IP protection.\n\n## Contributing\n\n### Code Standards\n- **Rust**: Follow Rust API guidelines and idioms\n- **TypeScript**: Follow Airbnb style guide\n- **Testing**: 80%+ code coverage required\n- **Documentation**: All public APIs documented\n\n### Pull Request Process\n1. Create a feature branch\n2. Implement changes with tests\n3. Update documentation\n4. Create pull request\n5. Code review and approval\n6. Automated testing passes\n7. Merge and tag release\n\n### Adding New Libraries\n1. Create the library structure\n2. Add to workspace configuration\n3. Implement comprehensive tests\n4. Add documentation\n5. Update CI/CD pipelines\n\n## Migration Guide\n\n### From Monolithic Services\n1. **Identify duplicated code** in current services\n2. **Extract to shared libraries** following the patterns above\n3. **Update service dependencies** to use shared libraries\n4. **Test integration** and compatibility\n5. **Remove duplicated code** from services\n\n### Example Migration\n```rust\n// Before: Duplicated error types\n#[derive(Debug, thiserror::Error)]\npub enum MyServiceError {\n    #[error(\"Not found: {resource}\")]\n    NotFound { resource: String },\n    // ... more duplicated error types\n}\n\n// After: Use shared error types\nuse cloudshuttle_error_handling::ApiError;\n\nimpl From\u003cApiError\u003e for MyServiceError {\n    fn from(error: ApiError) -\u003e Self {\n        match error {\n            ApiError::NotFound { resource } =\u003e MyServiceError::NotFound { resource },\n            // ... map other errors\n        }\n    }\n}\n```\n\n## Support\n\n### Documentation\n- **[USAGE_GUIDE.md](USAGE_GUIDE.md)** - How to use CloudShuttle libraries (Git dependencies, tags, setup)\n- **[CRATES_OVERVIEW.md](CRATES_OVERVIEW.md)** - Detailed crate descriptions and examples\n- **[docs/consumption/README.md](docs/consumption/README.md)** - Advanced consumption guide\n- [docs/consumption/QUICK_REFERENCE.md](docs/consumption/QUICK_REFERENCE.md) - Quick reference guide\n- [Rust Libraries Guide](docs/rust-libraries.md)\n- [TypeScript Libraries Guide](docs/typescript-libraries.md)\n- [Versioning Strategy](docs/versioning.md)\n- [Contributing Guide](docs/contributing.md)\n\n### Issues and Support\n- **GitHub Issues**: Bug reports and feature requests\n- **Discussions**: Questions and community support\n- **Documentation**: Comprehensive API documentation\n\n---\n\n## Quality Assurance\n\n### Automated Testing\n- **Unit Tests**: All public APIs tested\n- **Integration Tests**: Cross-library compatibility\n- **Contract Tests**: API compatibility validation\n- **Performance Tests**: Benchmarking and optimization\n\n### Code Quality\n- **Linting**: Clippy for Rust, ESLint for TypeScript\n- **Formatting**: rustfmt and Prettier\n- **Security**: Automated security scanning\n- **Coverage**: 80%+ test coverage required\n\n### Release Quality\n- **Automated Testing**: All tests pass before release\n- **API Compatibility**: Breaking changes flagged\n- **Documentation**: Updated for all changes\n- **Changelog**: Release notes for all changes\n\nThis shared libraries repository serves as the foundation for consistent, maintainable, and high-quality code across the entire CloudShuttle platform.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloud-shuttle%2Fcloudshuttle-shared","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloud-shuttle%2Fcloudshuttle-shared","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloud-shuttle%2Fcloudshuttle-shared/lists"}