{"id":48435886,"url":"https://github.com/bubustack/core","last_synced_at":"2026-04-06T13:01:18.116Z","repository":{"id":346993075,"uuid":"1192458001","full_name":"bubustack/core","owner":"bubustack","description":"Shared contracts, templating engine, and runtime primitives for BubuStack. Used by bobrapet, bobravoz-grpc, and bubu-sdk-go to keep shared behavior identical across the platform.","archived":false,"fork":false,"pushed_at":"2026-03-26T08:59:21.000Z","size":104,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-27T03:05:16.561Z","etag":null,"topics":["bubustack","contracts","controller-runtime","go","golang","grpc","kubernetes","platform","runtime","sdk","shared-library","templating","transport","workflow-orchestration"],"latest_commit_sha":null,"homepage":"https://bubustack.io/","language":"Go","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/bubustack.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","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},"funding":{"github":["bubustack"]}},"created_at":"2026-03-26T08:33:38.000Z","updated_at":"2026-03-26T08:54:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bubustack/core","commit_stats":null,"previous_names":["bubustack/core"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/bubustack/core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bubustack%2Fcore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bubustack%2Fcore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bubustack%2Fcore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bubustack%2Fcore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bubustack","download_url":"https://codeload.github.com/bubustack/core/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bubustack%2Fcore/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31473271,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-06T08:36:52.050Z","status":"ssl_error","status_checked_at":"2026-04-06T08:36:51.267Z","response_time":112,"last_error":"SSL_read: 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":["bubustack","contracts","controller-runtime","go","golang","grpc","kubernetes","platform","runtime","sdk","shared-library","templating","transport","workflow-orchestration"],"created_at":"2026-04-06T13:01:16.087Z","updated_at":"2026-04-06T13:01:18.109Z","avatar_url":"https://github.com/bubustack.png","language":"Go","readme":"# 🌐 core — Shared Primitives for BubuStack\n\n[![Go Reference](https://pkg.go.dev/badge/github.com/bubustack/core.svg)](https://pkg.go.dev/github.com/bubustack/core)\n[![Go Report Card](https://goreportcard.com/badge/github.com/bubustack/core)](https://goreportcard.com/report/github.com/bubustack/core)\n\n`core` is the shared foundation layer for the BubuStack ecosystem. It\ncentralizes contracts, templating behavior, and runtime helpers that must stay\nidentical across **bobrapet** (operator), **bobravoz-grpc** (transport hub),\nand **bubu-sdk-go** (runtime SDK).\n\n## 🔗 Quick Links\n\n- API reference: https://pkg.go.dev/github.com/bubustack/core\n- Issues: https://github.com/bubustack/core/issues\n- Support: [SUPPORT.md](./SUPPORT.md)\n- Security policy: [SECURITY.md](./SECURITY.md) (use GitHub Security Advisories for vulnerability reports)\n\n## 🌟 Key Features\n\n- **Canonical shared contracts** for env vars, annotations, labels, config keys, and index fields.\n- **Templating engine** with normalization, validation, path resolution, storage-ref detection, and shared evaluation rules.\n- **Runtime helpers** for env injection, naming, identity, stage metadata, operator config, and feature toggles.\n- **Transport primitives** for binding envelopes, protocol validation, connector config, dial/listen behavior, and TLS setup.\n- **Shared API surface discipline** so downstream repos do not re-implement behavior that should remain centralized.\n\n## 🏗️ Architecture\n\n| Package | Description |\n|---------|-------------|\n| `contracts` | Canonical annotations, labels, env vars, config keys, and index constants shared across repos. |\n| `templating` | Shared template normalization, validation, evaluation, path lookup, storage-ref detection, and caching. |\n| `runtime/bootstrap` | Shared startup registration and structured bootstrap logging helpers. |\n| `runtime/env` | Deterministic env builders for gRPC tuning, debug flags, and timestamps. |\n| `runtime/featuretoggles` | Shared telemetry, trace propagation, logging, and metrics toggle wiring. |\n| `runtime/identity` | StoryRun-safe label and service-account naming helpers. |\n| `runtime/naming` | DNS-safe resource name composition helpers. |\n| `runtime/operatorconfig` | Shared ConfigMap-backed operator config manager for controller-runtime consumers. |\n| `runtime/stage` | Structured StoryRun/step metadata helpers for logs and related shared metadata flow. |\n| `runtime/storage` | Storage provider env, secret, timeout, and volume wiring helpers. |\n| `runtime/transport` | Binding envelopes, protocol checks, and shared transport env helpers. |\n| `runtime/transport/connector` | Connector config, dial/listen helpers, TLS setup, and runtime tunables. |\n\n\u003e If a behavior must stay identical between operator, hub, and SDK, it belongs\n\u003e here with tests.\n\n## 🚀 Quick Start\n\n### 1. Add the module\n\n```bash\ngo get github.com/bubustack/core@latest\n```\n\n### 2. Import the helpers you need\n\n```go\nimport (\n\t\"github.com/bubustack/core/contracts\"\n\tcoreenv \"github.com/bubustack/core/runtime/env\"\n\toperatorconfig \"github.com/bubustack/core/runtime/operatorconfig\"\n\tcoretransport \"github.com/bubustack/core/runtime/transport\"\n)\n```\n\n### 3. Use the shared primitives\n\n- Use `contracts` for stable keys such as `contracts.StoryRunLabelKey`.\n- Use `coreenv.BuildGRPCTuningEnv` and `coreenv.AppendStartedAtEnv` when wiring workloads.\n- Use `coretransport.EncodeBindingEnvelope` and `coretransport.ParseBindingPayload` for transport binding serialization.\n- Use `operatorconfig.NewManager` when you need shared ConfigMap-backed runtime settings.\n\n## 🛠️ Local Development\n\n### Prerequisites\n\n- Go 1.25.1 or newer (matching `go.mod`)\n- `make`\n\n### Setup\n\n1. Clone your fork of `core`.\n2. Run `make help` to inspect available targets.\n3. Run `make test` before opening a change.\n\n### Common commands\n\n```bash\nmake build\nmake test\nmake test-coverage\nmake lint\n```\n\nRelease automation is managed by Release Please. Conventional Commits feed\n`CHANGELOG.md` and release PR generation.\n\n## 📢 Support, Security, and Changelog\n\n- See [SUPPORT.md](./SUPPORT.md) for help channels and support expectations.\n- See [SECURITY.md](./SECURITY.md) for vulnerability reporting. Security issues must go through GitHub Security Advisories, not public issues or email.\n- See [CHANGELOG.md](./CHANGELOG.md) for release history and upcoming shared-library changes.\n\n## 🤝 Community\n\n- Code of Conduct: [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)\n- Discord: https://discord.gg/dysrB7D8H6\n\n## 📄 License\n\nCopyright 2025 BubuStack.\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n","funding_links":["https://github.com/sponsors/bubustack"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbubustack%2Fcore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbubustack%2Fcore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbubustack%2Fcore/lists"}