Hacktoberfest 2026:维护者为十月标记出来的 issue,仍然开放、适合新手。 浏览 Hacktoberfest issue

refactor(providers)!: make provider behavior explicit in imported profiles

未关闭
#3,442 0 条评论 1 个 reaction 已指派 0 人 在 GitHub 查看

还没有人认领这个 Issue。

评估

难度
5/5
预计耗时
一周以上
新手友好度
35/100
Issue 类型
重构
描述清晰度
基本清楚
活跃度
活跃
技术栈
rust

调研方向

从 crates/openshell-providers/src/lib.rs 中的 ProviderRegistry::new 和 inject_env_for_profile_id 开始,然后检查 google_cloud.rs、vertex.rs、proto/openshell.proto 以及 middleware services 的入口点。在更改 schema 或文档之前,盘点每一种已编译行为并确定其处理方式。完成的标准是:forked profile IDs 保持原有行为,缺失的 adapters fail closed,过时的 discovery APIs 得到解决,并记录 middleware 的分类。

由索引模型根据 Issue 内容生成。

描述

state:triage-needed

Sub-issue of #3171 (provider boundary in step 5). Follows #3299 / PR #3383, which made provider profiles import-only. Coordinated pre-0.1.0 breaking change under #2565.

User Story

As an operator, I want an imported provider profile to declare every behavior it activates, so I can inspect, fork, and rename the profile without silently changing the sandbox environment.

Problem Statement

#3299 removed the compiled provider profile catalog, but two compiled adapters remain:

  • google-cloud projects provider config into GCP SDK variables and sets GCE_METADATA_HOST.
  • google-vertex-ai projects project and region config into GCP and Vertex variables and sets a GOOSE_PROVIDER default.

ProviderRegistry::inject_env_for_profile_id selects these adapters by the resolved profile ID. Importing the same profile as google-cloud and acme-gcp therefore produces different environments even though the imported definitions are identical.

Other provider-specific behavior is also compiled rather than declared: Vertex discovery scans a fixed list of config variables, and child-environment preparation contains GCP-specific metadata and non-secret configuration handling. ProviderProfile can declare credential environment variables, but not non-secret config projection, fixed non-secret values, discovery config keys, or a required platform adapter.

Impact / Why This Matters

An imported profile is not currently its complete definition. Operators must preserve canonical IDs and know release-specific implementation details, or provider creation succeeds while the workload later fails because expected SDK configuration is absent. This contradicts the import-only contract and makes profile forks unsafe.

Proposed Design

Inventory every compiled provider behavior reachable from an imported profile and give it one disposition:

  1. Express in the profile. Add bounded declarative fields for generic non-secret behavior such as config-to-environment projection, fixed values, and discovery config keys. Do not introduce templating or scripting.
  2. Declare a platform adapter. If behavior is genuinely platform-specific, the profile names the required adapter. Import or attachment fails with a bounded diagnostic when the adapter is unavailable.
  3. Remove it. Delete behavior or APIs with no remaining caller, including ProviderDiscoverySpec and discover_with_spec unless a supported use is identified.

Projection must preserve the existing rule that caller-supplied environment values win. Linting must reject collisions between non-secret projection and credential env_vars.

Update the Google Cloud and Vertex examples so their YAML describes their complete environment and discovery effects. A fork imported under a different ID must behave identically to the canonical example.

Credential refresh strategies are out of scope because profiles already declare them.

Acceptance Criteria

  • Every compiled provider behavior reachable from an imported profile is inventoried as profile-declared, named platform adapter, or removed.
  • No provider behavior activates from the profile ID alone.
  • The Google Cloud and Vertex examples declare their complete non-secret environment and discovery effects.
  • A profile forked under another ID produces the same sandbox environment and discovery behavior as the canonical profile.
  • Environment projection never overwrites an existing value.
  • Import or attachment fails with a bounded diagnostic when a declared platform adapter is unavailable.
  • Profile lint rejects unknown adapters and collisions between non-secret projection and credential environment variables.
  • ProviderDiscoverySpec and discover_with_spec are removed or have a documented supported caller.
  • ProviderProfile.source and resource_version documentation no longer refers to built-in profiles or builtin provenance.
  • Provider examples, architecture/user documentation, and 0.1.0 migration notes describe the resulting contract.
  • Tests cover profile/proto round trips, forked-ID equivalence, collision handling, non-overwrite semantics, and unavailable adapters.

Alternatives Considered

  • Delete both adapters: restores a clean boundary but breaks existing GCP and Vertex workloads at upgrade.
  • Document ID-keyed behavior only: leaves profile forks behaviorally different and the binary authoritative for part of the profile definition.
  • Add a general templating language: unnecessarily turns reviewable profile data into executable configuration; bounded projection covers the observed generic cases.
  • Restore aliases: cannot support an unbounded operator catalog and reintroduces hidden ID coupling.

Technical Notes

  • crates/openshell-providers/src/lib.rs: ProviderRegistry registers the two remaining adapters and selects them by exact profile ID.
  • crates/openshell-providers/src/discovery.rs: discover_from_profile special-cases google-vertex-ai config keys.
  • crates/openshell-core/src/provider_credentials.rs: child environment preparation contains GCP-specific metadata and non-secret resolution.
  • crates/openshell-server/src/grpc/provider.rs: provider environment assembly and key-collision validation are the runtime integration points.
  • proto/openshell.proto and crates/openshell-providers/src/profiles.rs: the public profile schema and YAML/protobuf conversion currently lack this declaration surface.

Checklist

  • Existing issues and architecture documentation reviewed
  • Design proposal; implementation planning follows human disposition
主要语言
Rust
星标
8.7k
派生
1.3k
平均合并
2 天 6 小时
30 天内合并 PR
301

贡献指南

打开贡献指南

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

NVIDIA/OpenShell 的其他 Issue

查看 NVIDIA/OpenShell 的全部 Issue

相似的 Issue

更多 Rust Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。