diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..239ec81 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,14 @@ +root = true + +[*] +charset = utf-8 +end_of_line = lf +indent_style = space +insert_final_newline = true +trim_trailing_whitespace = true + +[*.{json,md,markdown,proto,toml,yaml,yml}] +indent_size = 2 + +[*.{md,markdown}] +trim_trailing_whitespace = false diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml new file mode 100644 index 0000000..967f38f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -0,0 +1,64 @@ +name: Bug report +description: Report a problem with the protocol, documentation, or repository tooling. +title: "[Bug]: " +body: + - type: markdown + attributes: + value: | + Thanks for helping improve OpenEngine. Include enough detail for someone else to reproduce or evaluate the problem. + + - type: checkboxes + id: existing-issues + attributes: + label: Existing issues + options: + - label: I searched the existing issues and did not find this problem. + required: true + + - type: dropdown + id: area + attributes: + label: Area + options: + - Protocol schema + - API documentation + - Repository tooling or CI + - Other + validations: + required: true + + - type: input + id: revision + attributes: + label: Schema revision or commit + description: Identify the schema revision, release tag, or commit where the problem occurs. + placeholder: "Schema revision 1 or commit SHA" + + - type: textarea + id: current-behavior + attributes: + label: Current behavior + description: What happens, and why is it incorrect or unclear? + validations: + required: true + + - type: textarea + id: expected-behavior + attributes: + label: Expected behavior + description: What should happen instead? + validations: + required: true + + - type: textarea + id: reproduction + attributes: + label: Reproduction or example + description: Provide the smallest request, response, schema excerpt, command, or link that demonstrates the problem. + render: shell + + - type: textarea + id: context + attributes: + label: Additional context + description: Add relevant engine, client, distributed framework, or environment details. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..2ebc0e2 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: true +contact_links: + - name: Security vulnerability + url: https://github.com/ai-dynamo/openengine/security/policy + about: Report security issues privately by following the repository security policy. diff --git a/.github/ISSUE_TEMPLATE/protocol-change.yml b/.github/ISSUE_TEMPLATE/protocol-change.yml new file mode 100644 index 0000000..e2eb49a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/protocol-change.yml @@ -0,0 +1,91 @@ +name: Protocol change +description: Propose a change to the OpenEngine gRPC contract. +title: "[Protocol]: " +body: + - type: markdown + attributes: + value: | + OpenEngine is a pre-adoption API draft, so direct schema changes are allowed. A proposal should still define portable behavior precisely enough for independent clients and engines to agree. + + - type: checkboxes + id: existing-issues + attributes: + label: Existing proposals + options: + - label: I searched the existing issues and did not find this proposal. + required: true + + - type: dropdown + id: consumers + attributes: + label: Intended consumers + description: Who needs this behavior? + options: + - Direct engine clients + - Distributed frameworks + - Both direct clients and distributed frameworks + - Engine implementations only + - Other + validations: + required: true + + - type: textarea + id: problem + attributes: + label: Problem and use case + description: Describe the portable behavior that cannot be represented cleanly today. + validations: + required: true + + - type: textarea + id: evidence + attributes: + label: Evidence from engine protocols + description: Link to or summarize equivalent behavior in native engine protocols or implementations. + + - type: textarea + id: contract + attributes: + label: Proposed contract + description: Sketch the messages, fields, enums, or RPC behavior you propose. Protobuf is encouraged but not required. + render: proto + validations: + required: true + + - type: textarea + id: presence + attributes: + label: Presence, defaults, and validation + description: Define absent, zero, empty, default, invalid, and mutually exclusive states where applicable. + validations: + required: true + + - type: textarea + id: lifecycle + attributes: + label: Request and response lifecycle + description: Define acceptance, streaming, terminal success, cancellation, and error behavior affected by this change. + + - type: textarea + id: discovery + attributes: + label: Discovery and capability impact + description: Explain how clients determine whether an engine supports the behavior, or why no discovery change is needed. + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Describe simpler contract shapes or existing fields you considered reusing. + + - type: checkboxes + id: readiness + attributes: + label: Proposal checklist + options: + - label: The behavior is portable and does not expose one engine's internal scheduler model as the common API. + required: true + - label: I have identified the corresponding documentation changes. + required: true diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..e3abdf6 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,30 @@ +## Summary + + + +## Why + + + +## Validation + + + +- [ ] `buf build` +- [ ] `buf lint` +- [ ] Markdown and links checked when documentation changed +- [ ] Commits include a DCO sign-off + +## Protocol checklist + + + +- [ ] The canonical proto and API documentation are synchronized +- [ ] Presence, defaults, and invalid states are defined +- [ ] Acceptance, streaming, terminal, and error behavior are defined +- [ ] Discovery and capability impacts are documented +- [ ] Intentional schema rewrites are called out clearly + +## Additional context + + diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..560905d --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,66 @@ +name: Docs + +on: + push: + branches: + - main + paths: + - "**/*.md" + - ".markdownlint-cli2.yaml" + - ".lychee.toml" + - ".github/workflows/docs.yml" + pull_request: + paths: + - "**/*.md" + - ".markdownlint-cli2.yaml" + - ".lychee.toml" + - ".github/workflows/docs.yml" + +permissions: + contents: read + +jobs: + markdown: + name: Markdown + runs-on: ubuntu-latest + steps: + - name: Check out repository + uses: actions/checkout@v6 + + - name: Set up Node.js + uses: actions/setup-node@v6 + with: + node-version: "24" + + - name: Lint Markdown + run: npx --yes markdownlint-cli2@0.23.0 "**/*.md" + + links: + name: Links + runs-on: ubuntu-latest + steps: + - name: Check out repository + uses: actions/checkout@v6 + + - name: Install Lychee + env: + LYCHEE_SHA256: 73657a111819a30c47c08352896796f23d64e4eb2b3ed39b6d32149241566fc5 + LYCHEE_VERSION: v0.24.2 + run: | + archive="${RUNNER_TEMP}/lychee.tar.gz" + curl --fail --location --retry 3 --show-error \ + --output "${archive}" \ + "https://github.com/lycheeverse/lychee/releases/download/lychee-${LYCHEE_VERSION}/lychee-x86_64-unknown-linux-musl.tar.gz" + printf '%s %s\n' "${LYCHEE_SHA256}" "${archive}" | sha256sum --check - + tar --extract --gzip --file "${archive}" \ + --directory "${RUNNER_TEMP}" \ + --strip-components 1 \ + lychee-x86_64-unknown-linux-musl/lychee + + - name: Check links + run: | + "${RUNNER_TEMP}/lychee" \ + --config .lychee.toml \ + --root-dir "${GITHUB_WORKSPACE}" \ + --no-progress \ + './**/*.md' diff --git a/.lychee.toml b/.lychee.toml new file mode 100644 index 0000000..bbc7343 --- /dev/null +++ b/.lychee.toml @@ -0,0 +1,3 @@ +exclude = ["^mailto:"] +exclude_all_private = true +exclude_loopback = true diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml new file mode 100644 index 0000000..7880919 --- /dev/null +++ b/.markdownlint-cli2.yaml @@ -0,0 +1,10 @@ +config: + MD013: false + MD033: + allowed_elements: + - a + - h1 + - img + - p + - strong + MD041: false diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 93ed46b..b678ed1 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -131,4 +131,4 @@ For answers to common questions about this code of conduct, see the FAQ at [v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html [Mozilla CoC]: https://github.com/mozilla/diversity [FAQ]: https://www.contributor-covenant.org/faq -[translations]: https://www.contributor-covenant.org/translations \ No newline at end of file +[translations]: https://www.contributor-covenant.org/translations diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 811dd88..74417b5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -45,7 +45,7 @@ git commit -s -m "Add a concise, descriptive message." This appends the following to your commit message: -``` +```text Signed-off-by: Your Name ``` @@ -53,7 +53,7 @@ Use your real name (no pseudonyms or anonymous contributions) and an email that matches your commit author address. By signing off, you agree to the Developer Certificate of Origin (DCO), reproduced in full below. -``` +```text Developer Certificate of Origin Version 1.1 diff --git a/README.md b/README.md index 4e20cf9..f80a5ff 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ scheduler implementation details. | Without a shared contract | With OpenEngine | | --------------------------------------------------- | --------------------------------------------------- | -| Engine-specific clients and framework integrations | One generated service contract | +| Engine-specific clients and framework integrations | One generated service contract | | Configuration duplicated into sidecars | Engine capabilities discovered over RPC | | Engine upgrades coupled to framework code | Engine-native execution behind a common endpoint | | Ad hoc cancellation and failure behavior | Explicit lifecycle and terminal error semantics | @@ -130,7 +130,8 @@ buf build buf lint ``` -Buf lint runs in GitHub Actions for schema pull requests. +Buf lint, Markdown lint, and link checks run in GitHub Actions for relevant +pull requests. ### Generate Python bindings diff --git a/SECURITY.md b/SECURITY.md index f56e631..5f7f548 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -17,15 +17,22 @@ limitations under the License. # Report a Security Vulnerability -To report a potential security vulnerability in any NVIDIA product, please use either: +To report a potential security vulnerability in any NVIDIA product, please use +either: + * This web form: [Security Vulnerability Submission Form](https://www.nvidia.com/en-us/support/submit-security-vulnerability/), or * Send email to: [NVIDIA PSIRT](mailto:psirt@nvidia.com) -If reporting a potential vulnerability via email, please encrypt it using NVIDIA’s public PGP key ([see PGP Key page](https://www.nvidia.com/en-us/security/pgp-key/)) and include the following information: +If reporting a potential vulnerability via email, please encrypt it using +NVIDIA’s public PGP key +([see PGP Key page](https://www.nvidia.com/en-us/security/pgp-key/)) and include +the following information: + 1. Product/Driver name and version/branch that contains the vulnerability 2. Type of vulnerability (code execution, denial of service, buffer overflow, etc.) 3. Instructions to reproduce the vulnerability 4. Proof-of-concept or exploit code 5. Potential impact of the vulnerability, including how an attacker could exploit the vulnerability -See https://www.nvidia.com/en-us/security/ for past NVIDIA Security Bulletins and Notices. +See [NVIDIA Product Security](https://www.nvidia.com/en-us/security/) for past +NVIDIA Security Bulletins and Notices. diff --git a/docs/api.md b/docs/api.md index 2d4a20b..fe8d3a3 100644 --- a/docs/api.md +++ b/docs/api.md @@ -542,8 +542,8 @@ OpenEngine should support two KV-event modes: 1. **Native OpenEngine stream:** `SubscribeKvEvents` returns envelopes containing typed protobuf batches. -2. **Compatibility source discovery:** `GetKvEventSources` advertises existing engine-native sources such as SGLang/vLLM ZMQ publishers. - +2. **Compatibility source discovery:** `GetKvEventSources` advertises existing + engine-native sources such as SGLang/vLLM ZMQ publishers. ```protobuf message GetKvConnectorInfoRequest {} @@ -872,7 +872,7 @@ enum ErrorCode { Errors have exactly one transport based on when and where they occur: | Phase | Representation | Stream termination | -|---|---|---| +| --- | --- | --- | | Before request acceptance | Non-OK gRPC status | No response event | | Accepted request, application failure | Exactly one terminal `EngineError` event | gRPC `OK` after the event | | Transport or gRPC framework failure | Non-OK gRPC status | No synthesized `EngineError` | diff --git a/docs/motivation.md b/docs/motivation.md index 4e59d2f..667ccdc 100644 --- a/docs/motivation.md +++ b/docs/motivation.md @@ -58,7 +58,7 @@ request and control data needed across the process boundary. ## What the protocol covers | Area | Contract | -|---|---| +| --- | --- | | Generation | Streaming tokens, usage, finish state, and errors | | Discovery | Engine, model, role, topology, limits, and capabilities | | Lifecycle | Health, abort, and drain |