From 361325ff31e215e50d28d623b6423f95415e1646 Mon Sep 17 00:00:00 2001 From: Akanksha Trehun Date: Wed, 11 Nov 2026 13:18:18 +0530 Subject: [PATCH] Rewrite the README around how the repository fits together Add an overview of how extensions, bindings, profilers and platforms connect, a Redis cache example followed from extension to profile, a description of every top-level folder with a diagram of binding generation, status and bindings columns in the extensions table, and TypeScript and Python usage next to Go. Correct the Source Control identifier and list the current Amazon S3 release. --- README.md | 164 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 129 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 8ccb9d8..31edb1f 100644 --- a/README.md +++ b/README.md @@ -1,50 +1,47 @@ # Runtime Conditions Extensions -Runtime Conditions is currently seeking adoption by an established parent project. The repositories in this organization are split for hands-on usability, review, demos, and implementation feedback. They are not intended to present Runtime Conditions as a standalone foundation or competing project. +Runtime Conditions is a portable declaration of what one workload needs from outside itself, such as APIs, datastores, caches, and configuration, without the actual values. This repository defines the vocabulary that Runtime Conditions profiles use, and generates code packages so developers can declare those needs in code. Start here: https://runtimeconditions.github.io/ -## Purpose - -This repository contains Runtime Conditions extension definitions, declaration packages, semantic overlays, and extension-maintenance automation. Extension definitions own vocabulary and validation. Language declaration packages provide no-op source declarations that generators can read. +## How it fits together -Extension release identity, immutability, provenance, and SDK compatibility are defined in [`EXTENSION_RELEASES.md`](EXTENSION_RELEASES.md). +The core [spec](https://github.com/runtimeconditions/spec/blob/main/docs/sixth-draft.md#5-extensions) defines the shape of a profile, but not its words. Extensions define the words (kinds, interface types, interface fields, and allowed values) and the rules for using them. A profile lists every extension it uses by its exact identifier URL. Bindings are generated packages that let developers declare a workload's needs in code. A profiler reads those declarations and writes the profile, and a platform validates the profile against the extensions it lists. -Operation-oriented extensions use the authoring contract in [`SERVICE_OPERATIONS_SEMANTIC_BRIDGES.md`](SERVICE_OPERATIONS_SEMANTIC_BRIDGES.md). A semantic bridge references an authoritative Smithy, OpenAPI, protobuf, or comparable source when available and uses a separate Service Operations Inventory only as a fallback. +image -## Extensions -Per the [spec](https://github.com/runtimeconditions/spec/blob/main/docs/sixth-draft.md#5-extensions), first-party extensions are extensions like any other - there's no separate "core vocabulary" tier, and no notion of an extension being owned by this project versus anyone else's. Every extension lives together under `catalog/`, declared and resolved the same way regardless of who authored it: +## Here is an example -| Extension | Identifier | Path | -| --- | --- | --- | -| Common Integrations | `https://runtimeconditions.io/extensions/rc/common-integrations/v1alpha1/runtimeconditions.extension.yaml` | [`catalog/rc/common-integrations/`](catalog/rc/common-integrations/) | -| Env Configuration | `https://runtimeconditions.io/extensions/rc/env-configuration/v1alpha1/runtimeconditions.extension.yaml` | [`catalog/rc/env-configuration/`](catalog/rc/env-configuration/) | -| Source Control | `https://runtimeconditions.io/extensions/source-control/0.1.0/runtimeconditions.extension.yaml` | [`catalog/rc/source-control/`](catalog/rc/source-control/) | -| Amazon S3 | `https://runtimeconditions.io/extensions/aws/s3/0.1.0/runtimeconditions.extension.yaml` | [`catalog/aws/s3/`](catalog/aws/s3/) | -| Kubernetes API | `https://runtimeconditions.io/extensions/kubernetes/api/0.1.0/runtimeconditions.extension.yaml` | [`catalog/kubernetes/api/`](catalog/kubernetes/api/) | -| NATS | `https://runtimeconditions.io/extensions/nats/service/0.1.0/runtimeconditions.extension.yaml` | [`catalog/nats/service/`](catalog/nats/service/) | -| Google Analytics | `https://runtimeconditions.io/extensions/google/analytics/0.1.0/runtimeconditions.extension.yaml` | [`catalog/google/analytics/`](catalog/google/analytics/) | +This example follows one need, a Redis cache, from the extension to the profile. -## Folder layout +The Common Integrations extension defines the `cache` kind, ties the `key_value` interface type to it, and allows `redis` as its engine. From [`catalog/rc/common-integrations/common-integrations-v1alpha1.yaml`](catalog/rc/common-integrations/common-integrations-v1alpha1.yaml): -- `catalog/` - every extension, first-party or community, lives here as `//`. First-party extensions that aren't tied to an external vendor or project sit under `rc/` (`rc/common-integrations/`, `rc/env-configuration/`, `rc/source-control/`) - it's a namespace like any other, not a special tier. Everything else is namespaced by vendor or project (`aws/s3/`, `google/analytics/`, `kubernetes/api/`, `nats/service/`). The nesting is consistent for every entry, whether a namespace will only ever have one extension (`kubernetes/`, `nats/`) or many (`aws/`, `google/`, `rc/`) - we're not picking a different shape per case. -- `tooling/` - automation shared across extensions, not extensions themselves. Still figuring out the right shape for this one. - - `common/` the shared Python helpers (e.g. `serialization.py`) every extension's `tools/` imports from, so a fix only has to happen in one place. - - `smithy-runtime-conditions/` the external compiler used to prove semantic-bridge generation against AWS's public Smithy models before proposing an internal AWS generator integration. +```yaml +spec: + kinds: + - name: api + - name: datastore + - name: cache -## Go bindings + interfaceTypes: + # ... + - name: key_value + targetKind: cache -Generated Go modules are public, use short import paths, and require Go 1.25 or later. -Consumers install them without GitHub credentials or private-module configuration. -After the first binding release is published: + # ... -```sh -go get runtimeconditions.io/x/rc/common@v0.1.0 -go get runtimeconditions.io/x/rc/env@v0.1.0 + fieldValues: + # ... + - field: interface.engine + targetKind: cache + targetType: key_value + values: + - redis + - memcached ``` -The package names match the public paths, so aliases are optional: +A Go workload declares the cache with the generated Common Integrations and Env Configuration bindings: ```go import ( @@ -65,18 +62,105 @@ func cache() common.Declaration { } ``` +A profiler turns that declaration into the profile's `extensions` entries and a `cache` condition: + +```yaml +extensions: + - https://runtimeconditions.io/extensions/rc/common-integrations/v1alpha1/runtimeconditions.extension.yaml + - https://runtimeconditions.io/extensions/rc/env-configuration/v1alpha1/runtimeconditions.extension.yaml +conditions: + - kind: cache + interface: + type: key_value + engine: redis + configuration: + env: + - name: REDIS_URL + property: url +``` + +The generated functions do nothing at runtime: the compiler checks the declaration, and the profiler reads it. + +## What's in this repository + +- `catalog/` - every extension, first-party or community, lives here as `//`. First-party extensions that aren't tied to an external vendor or project sit under `rc/` (`rc/common-integrations/`, `rc/env-configuration/`, `rc/source-control/`) - it's a namespace like any other, not a special tier. Everything else is namespaced by vendor or project (`aws/s3/`, `google/analytics/`, `kubernetes/api/`, `nats/service/`). The nesting is consistent for every entry, whether a namespace will only ever have one extension (`kubernetes/`, `nats/`) or many (`aws/`, `google/`, `rc/`) - we're not picking a different shape per case. +- `bindings/` - generated packages, one folder per extension and language (`bindings///`), written by the `binding-generate` workflow. Never edited by hand. +- `tooling/extension-bindings/` - the generator that turns extensions into bindings: the normalizer, the per-language emitters, and the orchestrator. See its [README](https://github.com/runtimeconditions/extensions/blob/main/tooling/extension-bindings/README.md). +- `tooling/smithy-runtime-conditions/` - the compiler that builds operation extensions, such as Amazon S3, from a provider's Smithy model. See its [README](https://github.com/runtimeconditions/extensions/blob/main/tooling/smithy-runtime-conditions/README.md). +- `tooling/common/` - shared Python helpers (e.g. `serialization.py`) that each extension's `tools/` imports, so a fix only has to happen in one place, and the extensions site build (`build_extensions_site.py`). +- `.github/` - the workflows that test, generate, and publish. +- [`EXTENSION_RELEASES.md`](https://github.com/runtimeconditions/extensions/blob/main/EXTENSION_RELEASES.md) - extension release identity, immutability, provenance, and SDK compatibility. +- [`SERVICE_OPERATIONS_SEMANTIC_BRIDGES.md`](https://github.com/runtimeconditions/extensions/blob/main/SERVICE_OPERATIONS_SEMANTIC_BRIDGES.md) - the authoring contract for operation-oriented extensions. A semantic bridge references an authoritative Smithy, OpenAPI, protobuf, or comparable source when available and uses a separate Service Operations Inventory only as a fallback. + +Bindings are produced from each extension definition in stages: + +image + + +## Extensions + +Per the [spec](https://github.com/runtimeconditions/spec/blob/main/docs/sixth-draft.md#5-extensions), first-party extensions are extensions like any other - there's no separate "core vocabulary" tier, and no notion of an extension being owned by this project versus anyone else's. Every extension lives together under `catalog/`, declared and resolved the same way regardless of who authored it. The status is the one each extension's own README gives. + +| Extension | Identifier | Path | Status | Bindings | +| --- | --- | --- | --- | --- | +| Common Integrations | `https://runtimeconditions.io/extensions/rc/common-integrations/v1alpha1/runtimeconditions.extension.yaml` | [`catalog/rc/common-integrations/`](catalog/rc/common-integrations/) | Draft — Request for Comments | Go, Python, TypeScript | +| Env Configuration | `https://runtimeconditions.io/extensions/rc/env-configuration/v1alpha1/runtimeconditions.extension.yaml` | [`catalog/rc/env-configuration/`](catalog/rc/env-configuration/) | Draft — Request for Comments | Go, Python, TypeScript | +| Source Control | `https://runtimeconditions.io/extensions/rc/source-control/0.1.0/runtimeconditions.extension.yaml` | [`catalog/rc/source-control/`](catalog/rc/source-control/) | Experimental | TypeScript | +| Amazon S3 | `https://runtimeconditions.io/extensions/aws/s3/0.2.0/runtimeconditions.extension.yaml` | [`catalog/aws/s3/`](catalog/aws/s3/) | Authoritative-model maintenance experiment — not yet an AWS-published extension | TypeScript | +| Kubernetes API | `https://runtimeconditions.io/extensions/kubernetes/api/0.1.0/runtimeconditions.extension.yaml` | [`catalog/kubernetes/api/`](catalog/kubernetes/api/) | Accepted local semantic release — ready for maintainer review before public publication | TypeScript | +| NATS | `https://runtimeconditions.io/extensions/nats/service/0.1.0/runtimeconditions.extension.yaml` | [`catalog/nats/service/`](catalog/nats/service/) | Initial semantic candidate for SDK-authorship and adapter review | TypeScript | +| Google Analytics | `https://runtimeconditions.io/extensions/google/analytics/0.1.0/runtimeconditions.extension.yaml` | [`catalog/google/analytics/`](catalog/google/analytics/) | Experimental | TypeScript | + +## Using the bindings + `tooling/extension-bindings/packages.yaml` defines each public module path, package name, version, and generated source directory. Future bindings use `runtimeconditions.io/x//`, such as `runtimeconditions.io/x/aws/s3` with package name `s3`. -The existing docs build invokes `tooling/common/build_extensions_site.py`, -which publishes Go discovery pages alongside extension definitions. The Go -source remains in `bindings//go`. Versions are published through +### Go + +Generated Go modules are public, use short import paths, and require Go 1.25 or later. +Consumers install them without GitHub credentials or private-module configuration: + +```sh +go get runtimeconditions.io/x/rc/common@v0.2.0 +go get runtimeconditions.io/x/rc/env@v0.2.0 +``` + +The package names match the public paths, so aliases are optional. + +The Go source remains in `bindings//go`. Versions are published through **Publish Go bindings** in GitHub Actions; see -[the binding publication workflow](tooling/extension-bindings/README.md#go-binding-publication). +[the binding publication workflow](https://github.com/runtimeconditions/extensions/blob/main/tooling/extension-bindings/README.md#go-binding-publication). + +### TypeScript + +TypeScript bindings are published to npm for all seven extensions and require Node.js 20.19 or later: + +```sh +npm install @runtimeconditions/common-integrations +``` + +```ts +import { cache, KeyValue, KeyValueEngine } from "@runtimeconditions/common-integrations"; + +export const sessions = cache(new KeyValue({ engine: KeyValueEngine.Redis })); +``` -## Local validation +### Python + +The Python bindings are not published to PyPI yet. The generated packages are in +[`bindings/common-integrations/python/`](https://github.com/runtimeconditions/extensions/tree/main/bindings/common-integrations/python) and +[`bindings/env-configuration/python/`](https://github.com/runtimeconditions/extensions/tree/main/bindings/env-configuration/python), and require Python 3.12 or later. + +```python +from runtimeconditions_common_integrations import KeyValue, KeyValueEngine, cache + +sessions = cache(KeyValue(engine=KeyValueEngine.REDIS)) +``` + +## Validating extensions locally From a sibling `go-rc-profiler` checkout: @@ -86,3 +170,13 @@ go run . validate-extensions -root ../extensions ``` Published extension identifiers are immutable semantic releases. A new semantic definition receives a new exact identifier; Runtime Conditions document `apiVersion` changes are independent. + +## Contributing + +See [`CONTRIBUTING.md`](https://github.com/runtimeconditions/extensions/tree/main?tab=contributing-ov-file) for the checks to run and the pull request conventions. +Never edit files under `bindings/` by hand change the emitter, the catalog entry, or the extension instead. + + +## Project status + +Runtime Conditions is currently seeking adoption by an established parent project. The repositories in this organization are split for hands-on usability, review, demos, and implementation feedback. They are not intended to present Runtime Conditions as a standalone foundation or competing project.