Skip to content

README.md

Latest commit

 

History

History
122 lines (89 loc) · 4.96 KB

README.md

File metadata and controls

122 lines (89 loc) · 4.96 KB

🌐 core — Shared Primitives for BubuStack

Go Reference Go Report Card

core is the shared foundation layer for the BubuStack ecosystem. It centralizes contracts, templating behavior, and runtime helpers that must stay identical across bobrapet (operator), bobravoz-grpc (transport hub), and bubu-sdk-go (runtime SDK).

🔗 Quick Links

🌟 Key Features

  • Canonical shared contracts for env vars, annotations, labels, config keys, and index fields.
  • Templating engine with normalization, validation, path resolution, storage-ref detection, and shared evaluation rules.
  • Runtime helpers for env injection, naming, identity, stage metadata, operator config, and feature toggles.
  • Transport primitives for binding envelopes, protocol validation, connector config, dial/listen behavior, and TLS setup.
  • Shared API surface discipline so downstream repos do not re-implement behavior that should remain centralized.

🏗️ Architecture

Package Description
contracts Canonical annotations, labels, env vars, config keys, and index constants shared across repos.
templating Shared template normalization, validation, evaluation, path lookup, storage-ref detection, and caching.
runtime/bootstrap Shared startup registration and structured bootstrap logging helpers.
runtime/env Deterministic env builders for gRPC tuning, debug flags, and timestamps.
runtime/featuretoggles Shared telemetry, trace propagation, logging, and metrics toggle wiring.
runtime/identity StoryRun-safe label and service-account naming helpers.
runtime/naming DNS-safe resource name composition helpers.
runtime/operatorconfig Shared ConfigMap-backed operator config manager for controller-runtime consumers.
runtime/stage Structured StoryRun/step metadata helpers for logs and related shared metadata flow.
runtime/storage Storage provider env, secret, timeout, and volume wiring helpers.
runtime/transport Binding envelopes, protocol checks, and shared transport env helpers.
runtime/transport/connector Connector config, dial/listen helpers, TLS setup, and runtime tunables.

If a behavior must stay identical between operator, hub, and SDK, it belongs here with tests.

🚀 Quick Start

1. Add the module

go get github.com/bubustack/core@latest

2. Import the helpers you need

import (
	"github.com/bubustack/core/contracts"
	coreenv "github.com/bubustack/core/runtime/env"
	operatorconfig "github.com/bubustack/core/runtime/operatorconfig"
	coretransport "github.com/bubustack/core/runtime/transport"
)

3. Use the shared primitives

  • Use contracts for stable keys such as contracts.StoryRunLabelKey.
  • Use coreenv.BuildGRPCTuningEnv and coreenv.AppendStartedAtEnv when wiring workloads.
  • Use coretransport.EncodeBindingEnvelope and coretransport.ParseBindingPayload for transport binding serialization.
  • Use operatorconfig.NewManager when you need shared ConfigMap-backed runtime settings.

🛠️ Local Development

Prerequisites

  • Go 1.26+ (matching go.mod)
  • make

Setup

  1. Clone your fork of core.
  2. Run make help to inspect available targets.
  3. Run make test before opening a change.

Common commands

make build
make test
make test-coverage
make lint

Release automation is managed by Release Please. Conventional Commits feed CHANGELOG.md and release PR generation.

📢 Support, Security, and Changelog

  • See SUPPORT.md for help channels and support expectations.
  • See SECURITY.md for vulnerability reporting. Security issues must go through GitHub Security Advisories, not public issues or email.
  • See CHANGELOG.md for release history and upcoming shared-library changes.

🤝 Community

📄 License

Copyright 2025 BubuStack.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.