{"id":35159470,"url":"https://github.com/autonomous-bits/nomos-provider-file","last_synced_at":"2026-02-18T00:10:21.535Z","repository":{"id":321998212,"uuid":"1087405109","full_name":"autonomous-bits/nomos-provider-file","owner":"autonomous-bits","description":"Nomos provider for file system access.","archived":false,"fork":false,"pushed_at":"2026-01-14T21:55:51.000Z","size":7828,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-15T02:21:20.771Z","etag":null,"topics":["configuration-management","filesystem","go","golang","provider"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/autonomous-bits.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":".github/CODEOWNERS","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-10-31T21:17:47.000Z","updated_at":"2026-01-14T21:55:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/autonomous-bits/nomos-provider-file","commit_stats":null,"previous_names":["autonomous-bits/nomos-provider-file"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/autonomous-bits/nomos-provider-file","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/autonomous-bits%2Fnomos-provider-file","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/autonomous-bits%2Fnomos-provider-file/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/autonomous-bits%2Fnomos-provider-file/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/autonomous-bits%2Fnomos-provider-file/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/autonomous-bits","download_url":"https://codeload.github.com/autonomous-bits/nomos-provider-file/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/autonomous-bits%2Fnomos-provider-file/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28486955,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T22:54:02.790Z","status":"ssl_error","status_checked_at":"2026-01-16T22:50:10.344Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["configuration-management","filesystem","go","golang","provider"],"created_at":"2025-12-28T17:54:14.705Z","updated_at":"2026-02-15T21:08:07.178Z","avatar_url":"https://github.com/autonomous-bits.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Nomos File Provider\n\nReference implementation of an external Nomos provider for file system access.\n\n[![License](https://img.shields.io/badge/License-MIT-blue.svg)](/LICENSE)\n[![Go Version](https://img.shields.io/badge/Go-1.25%2B-blue)](https://go.dev/)\n\n## Overview\n\nThis provider implements the Nomos Provider gRPC service contract to supply configuration data from local file system directories. It reads `.csl` files from a configured directory and makes them available to the Nomos compiler via gRPC.\n\n## Features\n\n- **Directory-based access**: Reads all `.csl` files from a configured directory\n- **gRPC interface**: Implements `nomos.provider.v1.ProviderService`\n- **Multi-instance support**: Work with multiple configuration directories simultaneously\n- **Atomic initialization**: Automatic rollback if any instance fails to initialize\n- **Health checks**: Built-in health monitoring\n- **Graceful shutdown**: Clean resource cleanup on termination\n\n## Multi-Instance Support\n\n**New in v0.1.1**: The file provider now supports multiple independent instances within a single service process. Each instance is identified by a unique alias and operates on its own directory.\n\n### Key Capabilities\n\n- **Independent Instances**: Initialize multiple provider instances with different directories\n- **Isolated Operations**: Each instance manages its own set of .csl files independently\n- **Atomic Guarantees**: If any initialization fails, all instances are rolled back to ensure clean state\n- **Enhanced Errors**: All error messages include the alias to identify which instance caused the error\n\n### Multi-Instance Usage Example\n\n```csl\n# Define multiple provider instances\nsource:\n  alias: 'local'\n  type: 'file'\n  version: '0.1.1'\n  directory: './configs'\n\nsource:\n  alias: 'shared'\n  type: 'file'\n  version: '0.1.1'\n  directory: '/etc/shared-configs'\n\n# Import from different instances\nimport:local:database    # reads ./configs/database.csl\nimport:shared:network    # reads /etc/shared-configs/network.csl\n```\n\n### Path Structure\n\nWith multi-instance support, fetch paths follow this structure:\n\n```\npath[0]: alias        # identifies the provider instance\npath[1]: filename     # base name without .csl extension\npath[2+]: nested keys # optional: navigate within the file\n```\n\nExamples:\n```go\n// Fetch entire file from \"local\" instance\npath: [\"local\", \"database\"]\n\n// Fetch nested key from \"shared\" instance  \npath: [\"shared\", \"network\", \"ports\", \"http\"]\n```\n\n### Error Handling\n\nAll errors include the alias for better debugging:\n\n```\n❌ provider instance \"local\" not found\n❌ file \"database\" not found in provider instance \"local\"\n❌ path element \"host\" not found in file \"database\" (provider instance \"local\")\n```\n\n### Initialization Guarantees\n\nThe provider ensures atomic initialization:\n\n```csl\nsource:\n  alias: 'instance1'\n  directory: './valid-path'    # ✅ succeeds\n\nsource:\n  alias: 'instance2'\n  directory: './invalid-path'  # ❌ fails\n  \n# Result: Both instances are rolled back\n# Service returns to clean empty state\n# Error message: \"rolled back all 1 instance(s)\"\n```\n\nThis prevents partial initialization states and ensures consistent behavior.\n\n## Usage\n\n### With Nomos CLI\n\nDeclare the provider in your `.csl` file:\n\n```csl\n# Single instance (v0.1.0 compatible)\nsource:\n  alias: 'configs'\n  type: 'file'\n  version: '0.1.1'\n  directory: './configs'\n\nimport:configs:database\n```\n\nRun `nomos init` to install the provider:\n\n```bash\nnomos init\n```\n\nThen build your configuration:\n\n```bash\nnomos build -p ./config.csl\n```\n\n### Standalone Testing\n\nThe provider can be run standalone for testing:\n\n```bash\n./nomos-provider-file\n```\n\nThe provider will:\n1. Start a gRPC server on a random available port\n2. Print `PROVIDER_PORT=\u003cport\u003e` to stdout\n3. Wait for RPC calls\n\n## Configuration\n\nThe provider accepts the following configuration in the `Init` RPC call:\n\n| Key | Type | Required | Description |\n|-----|------|----------|-------------|\n| `directory` | string | Yes | Absolute or relative path to directory containing `.csl` files |\n\n## Development\n\n### Prerequisites\n\n- Go 1.25+ or later\n- Protocol Buffers compiler (for regenerating proto stubs)\n- Local clone of the Nomos repository (for now, until modules are published)\n\n### Note on Dependencies\n\nThis provider currently uses `replace` directives in `go.mod` to reference the Nomos libraries locally. For production releases, these dependencies need to be published as proper Go modules or vendored into the repository.\n\n### Building\n\n```bash\nmake build\n```\n\n### Testing\n\n```bash\nmake test\n```\n\n### Running Locally\n\n```bash\ngo run ./cmd/provider\n```\n\n## Protocol\n\nThis provider implements the `nomos.provider.v1.ProviderService` gRPC contract:\n\n- **Init**: Initialize the provider with a directory path\n- **Fetch**: Retrieve a `.csl` file by base name (without extension)\n- **Info**: Return provider metadata (alias, version, type)\n- **Health**: Check provider health status\n- **Shutdown**: Gracefully shut down the provider\n\n### Fetch Path Format\n\n**Multi-Instance Format (v0.1.1+)**:\n\n```\npath: [\"alias\", \"filename\"]            → fetches from specific instance\npath: [\"alias\", \"filename\", \"key\"]     → fetches nested key\npath: [\"local\", \"database\"]            → fetches ./configs/database.csl\npath: [\"shared\", \"network\", \"ports\"]   → fetches /etc/configs/network.csl -\u003e ports\n```\n\n**Wildcard Expansion (v0.1.1+)**:\n\n```\npath: [\"alias\", \"filename\", \"*\"]     → returns the full object at that path (must be a map)\npath: [\"*\"]                           → merges all files in the directory, returns full object\n```\n\n**Single Instance Format (v0.1.0 compatible)**:\n\n```\npath: [\"database\"]      → fetches database.csl\npath: [\"network\"]       → fetches network.csl\npath: [\"app\", \"config\"] → fetches app.csl and navigates to config key\n```\n\n## Architecture\n\n```\n┌──────────────┐          gRPC           ┌─────────────────┐\n│    Nomos     │ ──────────────────────▶ │ Provider        │\n│   Compiler   │   Init/Fetch/Info/etc   │ (subprocess)    │\n└──────────────┘                         └─────────────────┘\n                                                  │\n                                                  ▼\n                                         ┌─────────────────┐\n                                         │  File System    │\n                                         │  (.csl files)   │\n                                         └─────────────────┘\n```\n\nThe provider:\n1. Is started as a subprocess by the Nomos compiler\n2. Listens on a random TCP port\n3. Parses `.csl` files from the configured directory\n4. Returns structured data via gRPC\n\n## Versioning\n\nThis project follows [Semantic Versioning](https://semver.org/):\n\n- **MAJOR**: Breaking changes to gRPC contract or behavior\n- **MINOR**: New features, backward compatible\n- **PATCH**: Bug fixes, backward compatible\n\n## License\n\nSee [LICENSE](LICENSE) file for details.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fautonomous-bits%2Fnomos-provider-file","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fautonomous-bits%2Fnomos-provider-file","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fautonomous-bits%2Fnomos-provider-file/lists"}