{"id":51223405,"url":"https://github.com/constructorfabric/gears-rust","last_synced_at":"2026-06-28T09:00:54.037Z","repository":{"id":362412773,"uuid":"1246435485","full_name":"constructorfabric/gears-rust","owner":"constructorfabric","description":"All-in-one open-source framework \u0026 middleware for enterprise-grade multi-tenant and multi-tier XaaS Services development","archived":false,"fork":false,"pushed_at":"2026-06-23T10:48:31.000Z","size":38428,"stargazers_count":14,"open_issues_count":292,"forks_count":23,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-23T12:43:05.067Z","etag":null,"topics":["account-management","agentic-ai","ai","benchmarks","cloud","genai","llm","microservices","middleware","modkit","multi-tenancy","multi-tier","rust","saas","security","serverless","xaas"],"latest_commit_sha":null,"homepage":"https://www.constructorfabric.org","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/constructorfabric.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":"MAINTAINERS.md","copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-22T07:31:40.000Z","updated_at":"2026-06-23T10:06:46.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/constructorfabric/gears-rust","commit_stats":null,"previous_names":["constructorfabric/cyberware-rust","constructorfabric/gears-rust"],"tags_count":1045,"template":false,"template_full_name":null,"purl":"pkg:github/constructorfabric/gears-rust","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/constructorfabric%2Fgears-rust","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/constructorfabric%2Fgears-rust/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/constructorfabric%2Fgears-rust/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/constructorfabric%2Fgears-rust/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/constructorfabric","download_url":"https://codeload.github.com/constructorfabric/gears-rust/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/constructorfabric%2Fgears-rust/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34882751,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"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":["account-management","agentic-ai","ai","benchmarks","cloud","genai","llm","microservices","middleware","modkit","multi-tenancy","multi-tier","rust","saas","security","serverless","xaas"],"created_at":"2026-06-28T09:00:40.050Z","updated_at":"2026-06-28T09:00:54.030Z","avatar_url":"https://github.com/constructorfabric.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Constructor Fabric Gears (Rust)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/constructorfabric/gears-rust/badge)](https://scorecard.dev/viewer/?uri=github.com/constructorfabric/gears-rust) [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/12050/badge)](https://www.bestpractices.dev/projects/12050)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/img/gears.png\" style='max-width: 800px' alt=\"Constructor Fabric Gears diagram\"\u003e\n\u003c/p\u003e\n\n**Gears** is a secure, modular XaaS framework and middleware, developed in Rust by the [Constructor Fabric Foundation](https://www.constructorfabric.org). It provides composable building blocks, domain components, and APIs with defense-in-depth security, multi-tenancy, and fine-grained access control built into every layer.\n\nGears is not a ready-to-use service. Instead, it is a set of well-integrated libraries that XaaS vendors can compose into their own products. Vendors decide which gears to include, how to combine them into services, and where to run them—from edge devices to Kubernetes clusters.\n\nGears span three broad categories:\n- **Core** gears for platform foundations such as API gateway, authentication/authorization, account management, etc;\n- **Serverless** gears for functions, workflows, and event-driven execution;\n- **GenAI** gears for chat, retrieval, prompt orchestration, and related AI capabilities.\n\nSee also:\n- [WHY_GEARS](docs/WHY_GEARS.md) explaining why to chose Rust/Gears for your XaaS project.\n- [OVERVIEW](docs/slides/1_OVERVIEW.md) HTML slides explaining the key Constructor Fabric Gears concepts.\n- [GEARS](docs/GEARS.md) for gears overview.\n\n**Five defining Gears characteristics:**\n\n1. **Secure XaaS framework with defense-in-depth** — Every API handler enforces authentication, authorization, tenant isolation, and scoped DB access by default. Security is structural, not opt-in, validated at build time using integrated dynamic lints.\n\n2. **Three-tier gear hierarchy** — *Gears Toolkit* (`libs/` — ToolKit, DB access, error model, API middleware), *System gears* (`gears/system/` — API gateway, authn/authz, tenancy, event system, resource groups, type registry), and *Service gears* (`gears/` — serverless runtime, GenAI subsystems, and domain-specific libraries).\n\n3. **Composable libraries, vendor-controlled deployment** — Each gear owns its API surface and database, communicates via a Rust-native SDK that facades local vs. remote calls, and is fully infrastructure-agnostic. Vendors choose which gears to bundle and whether to deploy single-process (edge/on-prem), multi-node (bare metal), or on Kubernetes.\n\n4. **Pre-integrated XaaS backbone** — Deep integration with multi-tenancy, licensing and quota management, usage collection, and event systems. Gears provides its own backbone capabilities, but each can be replaced or integrated with existing vendor infrastructure via plugins (e.g. subscription management, product catalog, provisioning, or license enforcement).\n\n5. **Extensible domain model via Global Type System** — Gears expose extensible domain objects whose metadata and types are customizable through [GTS](https://github.com/globaltypesystem/gts-spec) — define new event types, user settings, LLM model attributes, etc. CRUD API handlers support customization via hooks and callbacks as serverless functions and workflows.\n\n**Engineering principles:**\n- **Spec-Driven Development**: [Specification templates](docs/spec-templates/README.md) (PRD, Design, ADR, Feature) define what gets built *before* code is written. Every gear is well documented.\n- **Shift Left**: Custom [dylint](tools/dylint_lints/) architectural lints enforce design rules at compile time, alongside Clippy, [tests](#testing), fuzzing, and security audits in CI\n- **Quality First**: 90%+ test coverage target with unit, integration, E2E, performance, and security testing\n- **Core in Rust**: Compile-time safety, deep static analysis including project-specific lints, so more issues are prevented before review/runtime\n- **Monorepo**: All the core gears and contracts in one place for atomic refactors, consistent tooling/CI, and realistic local build + E2E testing\n\nSee the full architecture [MANIFEST](docs/ARCHITECTURE_MANIFEST.md) for more details, including rationales behind Rust and Monorepo choice.\n\nSee also [REPO_PLAYBOOK](docs/REPO_PLAYBOOK.md) with the registry of repository-wide artifacts (guidelines, rules, conventions, etc).\n\n## Quick Start\n\n### Prerequisites\n\n- Rust stable with Cargo ([Install via rustup](https://rustup.rs/))\n- Protocol Buffers compiler (`protoc`):\n  - macOS: `brew install protobuf`\n  - Linux: `apt-get install protobuf-compiler`\n  - Windows: Download from https://github.com/protocolbuffers/protobuf/releases\n- MariaDB/PostgreSQL/SQLite or in-memory database\n\n### CI/Development Commands\n\n```bash\n# Clone the repository\ngit clone --recurse-submodules \u003crepository-url\u003e\ncd gears-rust\n\nmake build      # Build libraries and example server binary\nmake test       # Run tests\nmake example    # Run toolkit example gear\n```\n\n### Running the Server\n\nThe Gears repository comes with an example server illustrating the gears APIs:\n\n```bash\n# Run an example server, see the API docs @ http://127.0.0.1:8087/cf/docs\nmake exammple\n\n# See API documentation:\n# $ make example\n# visit: http://127.0.0.1:8087/cf/docs\n\n# Check if server is ready (detailed JSON response)\ncurl http://127.0.0.1:8087/cf/health\n\n# Kubernetes-style liveness probe (simple \"ok\" response)\ncurl http://127.0.0.1:8087/healthz\n```\n\nOther quick start examples:\n\n```bash\n# Option 1: Run with SQLite database (recommended for development)\ncargo run --bin cf-gears-example-server -- --config config/quickstart.yaml run\n\n# Option 2: Run without database (no-db mode)\ncargo run --bin cf-gears-example-server -- --config config/no-db.yaml run\n\n# Option 3: Run with mock in-memory database for testing\ncargo run --bin cf-gears-example-server -- --config config/quickstart.yaml --mock run\n```\n\n### Example Configuration (config/quickstart.yaml)\n\n```yaml\n# Constructor Fabric Gears Configuration\n\n# Core server configuration (global section)\nserver:\n  home_dir: \"~/.cfgears\n\n# Database configuration (global section)\ndatabase:\n  url: \"sqlite://database/database.db\"\n  max_conns: 10\n  busy_timeout_ms: 5000\n\n# Logging configuration (global section)\nlogging:\n  default:\n    console_level: info\n    file: \"logs/cfgears.log\"\n    file_level: warn\n    max_age_days: 28\n    max_backups: 3\n    max_size_mb: 1000\n\n# Per-gear configurations moved under gears section\ngears:\n  api_gateway:\n    bind_addr: \"127.0.0.1:8087\"\n    enable_docs: true\n    cors_enabled: false\n```\n\n### Creating Your First Gear\n\nSee [TOOLKIT UNIFIED SYSTEM](docs/toolkit_unified_system/README.md) and [TOOLKIT_PLUGINS.md](docs/TOOLKIT_PLUGINS.md) for details.\n\n## Documentation\n\n- **[Architecture manifest](docs/ARCHITECTURE_MANIFEST.md)** - High-level overview of the architecture\n- **[Gears](docs/GEARS.md)** - List of all gears and their roles\n- **[TOOLKIT UNIFIED SYSTEM](docs/toolkit_unified_system/README.md) and [TOOLKIT_PLUGINS.md](docs/TOOLKIT_PLUGINS.md)** - how to add new gears.\n- **[Contributing](CONTRIBUTING.md)** - Development workflow and coding standards\n\n## Security\n\nGears apply defense-in-depth security across the entire development lifecycle — from Rust's compile-time safety guarantees and custom architectural lints, through compile-time tenant isolation and PDP/PEP authorization enforcement, to continuous fuzzing, dependency auditing, and automated security scanning in CI.\n\nSee **[Security Overview](docs/security/SECURITY.md)** for the full breakdown, including: Secure ORM with compile-time tenant scoping, authentication/authorization architecture (NIST SP 800-162 PDP/PEP model), 90+ Clippy deny-level rules, custom dylint architectural lints, cargo-deny advisory checks, ClusterFuzzLite continuous fuzzing, CodeQL/Scorecard/Snyk/Aikido scanners, and AI-powered PR review bots.\n\n## FIPS 140-3 support\n\nBuilt with `--features fips`, Gears route every TLS data-path cryptographic operation through a **CMVP-validated cryptographic module** — AWS-LC FIPS (Linux), Apple corecrypto (macOS), or Microsoft Windows CNG (Windows) — behind a single `rustls 0.23` state machine. Gears are *consumers* of those validated modules, not a CMVP-listed module themselves.\n\nSee **[Security Overview §9 — Cryptographic Stack \u0026 FIPS-140-3](docs/security/SECURITY.md#9-cryptographic-stack--fips-140-3)** for algorithm scope, build prerequisites, runtime/verification gates, and the full \"what this does and does not claim\" breakdown.\n\n## Configuration\n\n### YAML Configuration Structure\n\n```yaml\n# config/server.yaml\n\n# Global server configuration\nserver:\n  home_dir: \"~/.cfgears\"\n\n# Database configuration\ndatabase:\n  servers:\n    sqlite_users:\n      params:\n        WAL: \"true\"\n        synchronous: \"NORMAL\"\n        busy_timeout: \"5000\"\n      pool:\n        max_conns: 5\n        acquire_timeout: \"30s\"\n\n# Logging configuration\nlogging:\n  default:\n    console_level: info\n    file: \"logs/cf-gears.log\"\n    file_level: warn\n    max_age_days: 28\n    max_backups: 3\n    max_size_mb: 1000\n\n# Per-gear configuration\ngears:\n  api_gateway:\n    config:\n      bind_addr: \"127.0.0.1:8087\"\n      enable_docs: true\n      cors_enabled: true\n  users_info:\n    database:\n      server: \"sqlite_users\"\n      file: \"users_info.db\"\n    config:\n      default_page_size: 5\n      max_page_size: 100\n```\n\n### Environment Variable Overrides\n\nConfiguration supports environment variable overrides with `CF_` prefix:\n\n```bash\nexport CF_GEARS_DATABASE_URL=\"postgres://user:pass@localhost/db\"\nexport CF_GEARS_API_GATEWAY_BIND_ADDR=\"0.0.0.0:8080\"\nexport CF_GEARS_LOGGING_DEFAULT_CONSOLE_LEVEL=\"debug\"\n```\n\n## Testing\n\n```bash\nmake check           # full quality gate (fmt + clippy + test + security)\n```\n\nOther tests:\n\n```bash\nmake test            # unit tests (workspace)\nmake test-sqlite     # integration tests (SQLite, no external DB required)\nmake e2e-local       # end-to-end tests (builds + starts server automatically)\nmake e2e-local E2E_TARGET=testing/e2e/gears/file_parser/  # targeted end-to-end scope\nmake e2e-docker      # end-to-end tests (builds + starts server in Docker)\nmake coverage-unit   # unit test code coverage\nmake fuzz            # fuzz smoke tests (30 s per target)\n```\n\nOn **Windows** (no `make`), use the cross-platform Python scripts directly\n(invoke them with `python`; `python3` is often absent on Windows):\n\n```bash\npython tools/scripts/ci.py check          # full CI suite\npython tools/scripts/ci.py e2e-local      # end-to-end tests\npython tools/scripts/ci.py e2e-local -- testing/e2e/gears/file_parser/  # targeted end-to-end scope\npython tools/scripts/ci.py fuzz --seconds 60  # fuzz smoke run\n\npython tools/scripts/coverage.py unit      # unit-test code coverage\npython tools/scripts/coverage.py combined  # unit + e2e-local coverage\n```\n\nThese scripts need a few prerequisites on Windows:\n\n```bash\npip install -r testing/e2e/requirements.txt   # pytest + httpx (e2e tests)\npip install -r testing/requirements.txt        # PyYAML + requests (coverage.py)\ncargo install cargo-llvm-cov                    # coverage backend (or run `make setup`)\n```\n\nFor the complete test strategy, coverage policy, CI pipeline details, and all\navailable commands see **[docs/TESTING.md](docs/TESTING.md)**.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n## License\n\nThis project is licensed under the Apache 2.0 License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconstructorfabric%2Fgears-rust","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fconstructorfabric%2Fgears-rust","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconstructorfabric%2Fgears-rust/lists"}