Skip to content

Commit c77daab

Browse files
committed
docs(api): cut comments to what the code cannot say
Comments carry the mechanism, not the rationale; every argument removed here is in the design proposal or the PR. Where one claim appeared at several sites, the copy at the site that constrains the code stays. Assisted-by: LLM Signed-off-by: Timofei Larkin <[email protected]>
1 parent 069054b commit c77daab

18 files changed

Lines changed: 60 additions & 104 deletions

File tree

‎api/v1alpha1/applicationdefinition_credentials_types.go‎

Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -21,11 +21,8 @@ import (
2121
)
2222

2323
// ApplicationDefinitionCredentials declares the accounts of an application
24-
// kind and how the Cozystack API stores their passwords. Its presence is what
25-
// converts the kind: the API seeds one account Secret per account when an
26-
// application is written, serves a core.cozystack.io Credential per account,
27-
// and mints a password on request. The chart renders only references to the
28-
// account Secrets and never a password. See
24+
// kind and how the Cozystack API stores their passwords. Its presence converts
25+
// the kind to platform-minted credentials. See
2926
// design-proposals/user-secrets-api in cozystack/community.
3027
type ApplicationDefinitionCredentials struct {
3128
// Format is how a password is stored in the account Secret: the verifier the
@@ -62,8 +59,7 @@ const (
6259
// CredentialFormatBuiltIn names a function compiled into the API.
6360
CredentialFormatBuiltIn CredentialFormatKind = "BuiltIn"
6461
// CredentialFormatWebhook names an endpoint the API calls with the
65-
// plaintext. Declared so a block can carry it without a schema change; the
66-
// API refuses to serve a kind that uses it until the call is implemented.
62+
// plaintext. Declared, not served yet.
6763
CredentialFormatWebhook CredentialFormatKind = "Webhook"
6864
)
6965

‎api/v1alpha1/applicationdefinitions_types.go‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -62,8 +62,7 @@ type ApplicationDefinitionSpec struct {
6262
// Dashboard configuration for this resource
6363
Dashboard *ApplicationDefinitionDashboard `json:"dashboard,omitempty"`
6464

65-
// Credentials declares the kind's accounts and how the API stores their
66-
// passwords. Its presence converts the kind to platform-minted credentials.
65+
// Credentials converts the kind to platform-minted credentials.
6766
// +optional
6867
Credentials *ApplicationDefinitionCredentials `json:"credentials,omitempty"`
6968
}

‎internal/controller/applicationdefinition_helmreconciler.go‎

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -153,13 +153,11 @@ func expectedValuesFrom() []helmv2.ValuesReference {
153153
return store.ValuesFrom(nil, "", nil)
154154
}
155155

156-
// releaseValuesFrom returns the valuesFrom a release should carry under its
157-
// definition: the platform values, and for a kind whose block names a
158-
// valuesPath one entry per account, so a release created before the block
159-
// appeared gets the entries on its next reconcile. The accounts are resolved
160-
// from the release's values with the definition's schema defaults applied,
161-
// as the API resolves them on a write. An error means the values declare
162-
// accounts the API would refuse, and leaves the release as it is.
156+
// releaseValuesFrom returns the valuesFrom a release carries under its
157+
// definition, resolving the accounts with the definition's schema defaults as
158+
// the API does on a write, so a release created before the block appeared
159+
// gets its entries on reconcile. An error means values the API would refuse;
160+
// the release is left as it is.
163161
func releaseValuesFrom(hr *helmv2.HelmRelease, appDef *cozyv1alpha1.ApplicationDefinition) ([]helmv2.ValuesReference, error) {
164162
block := appDef.Spec.Credentials
165163
if block == nil || block.ValuesPath == "" {

‎packages/system/application-definition-crd/definition/cozystack.io_applicationdefinitions.yaml‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -63,9 +63,7 @@ spec:
6363
- singular
6464
type: object
6565
credentials:
66-
description: |-
67-
Credentials declares the kind's accounts and how the API stores their
68-
passwords. Its presence converts the kind to platform-minted credentials.
66+
description: Credentials converts the kind to platform-minted credentials.
6967
properties:
7068
accounts:
7169
description: |-

‎packages/system/cozystack-basics/templates/clusterroles.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -311,7 +311,7 @@ rules:
311311
- patch
312312
- delete
313313
# A mint replaces an account's password and shows the new one once, so it is
314-
# an admin's write, not a reader's; a custom role can grant revoke alone.
314+
# an admin's write, not a reader's.
315315
- apiGroups: ["core.cozystack.io"]
316316
resources:
317317
- credentials/mint

‎packages/system/cozystack-basics/tests/clusterroles-credentials_test.yaml‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -7,12 +7,10 @@ release:
77
name: cozystack-basics
88
namespace: cozy-system
99

10-
# A Credential is the view of one managed application account, and a mint on
11-
# it replaces the password and shows the new one once. Reading the view is a
12-
# view-tier grant; minting and revoking are admin writes, and the tenant
13-
# ServiceAccount, which the dashboard signs in with when OIDC is off, holds
14-
# both. The subresources are gated by verb create on their own resource
15-
# names, so a grant on credentials alone issues nothing.
10+
# Reading a Credential is a view-tier grant; minting and revoking are admin
11+
# writes, and the tenant ServiceAccount holds both. The subresources are gated
12+
# by verb create on their own resource names, so a grant on credentials alone
13+
# issues nothing.
1614
tests:
1715
- it: cozy:tenant:view:base grants read on core.cozystack.io credentials
1816
documentSelector:

‎pkg/apis/core/v1alpha1/credential_types.go‎

Lines changed: 5 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,15 @@
11
// SPDX-License-Identifier: Apache-2.0
22

3-
// Credential is the account record of one platform-generated credential of a
4-
// managed application: who can know the live password and who changed it. It
5-
// is a view over the account Secret the Cozystack API keeps per account, and
6-
// it never carries the password or the stored verifier. The password is
7-
// obtained once, through the mint subresource, and replaced through it. See
8-
// design-proposals/user-secrets-api in cozystack/community.
9-
103
package v1alpha1
114

125
import metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
136

147
// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
158

16-
// Credential is one account of a converted application.
9+
// Credential is the record of one account of a converted application: who can
10+
// know the live password and who changed it, never the password or its stored
11+
// form. It is a view over the account Secret the API keeps. See
12+
// design-proposals/user-secrets-api in cozystack/community.
1713
type Credential struct {
1814
metav1.TypeMeta `json:",inline"`
1915
metav1.ObjectMeta `json:"metadata,omitempty"`
@@ -105,8 +101,7 @@ type CredentialList struct {
105101
// CredentialRequest is the body and the answer of the mint and revoke
106102
// subresources of a Credential, in the shape of a Kubernetes TokenRequest: a
107103
// create on the subresource carries the request in spec and is answered with
108-
// the result in status, and nothing is stored. The password in a mint's answer
109-
// is the only place it ever exists outside the API's memory.
104+
// the result in status, and nothing is stored.
110105
type CredentialRequest struct {
111106
metav1.TypeMeta `json:",inline"`
112107
metav1.ObjectMeta `json:"metadata,omitempty"`

‎pkg/cmd/server/start.go‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -289,10 +289,8 @@ func resourceConfigFrom(defs []v1alpha1.ApplicationDefinition, hrFlags helmRelea
289289
}
290290
resourceConfig := &config.ResourceConfig{}
291291
for _, crd := range owned {
292-
// A credentials block the API cannot honour, declaring a format or a
293-
// source kind that is not built or a format it does not know, leaves
294-
// the kind unserved rather than served with passwords it cannot
295-
// issue, as a kind with an invalid name schema refuses writes.
292+
// A block the API cannot honour leaves the kind unserved; see
293+
// account.Validate.
296294
if err := account.Validate(crd.Spec.Credentials); err != nil {
297295
fmt.Printf("Skipping ApplicationDefinition %q: credentials block cannot be served: %v\n", crd.Name, err)
298296
continue

‎pkg/config/config.go‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -197,9 +197,8 @@ type ResourceConfig struct {
197197
type Resource struct {
198198
Application ApplicationConfig `yaml:"application"`
199199
Release ReleaseConfig `yaml:"release"`
200-
// Credentials is the kind's credentials block, copied from
201-
// spec.credentials of its ApplicationDefinition at start-up. nil for a
202-
// kind that is not converted to platform-minted credentials.
200+
// Credentials is the definition's spec.credentials; nil for a kind that is
201+
// not converted.
203202
Credentials *v1alpha1.ApplicationDefinitionCredentials `yaml:"credentials,omitempty"`
204203
}
205204

‎pkg/credentials/account/account.go‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -92,10 +92,9 @@ func SplitCredentialName(name string) (release, mapped string, ok bool) {
9292
return release, mapped, true
9393
}
9494

95-
// Validate reports whether the API can serve a kind with this block. A format
95+
// Validate reports whether the API can serve a kind with this block: a format
9696
// or a source kind that is declared but not built, an unknown built-in format,
97-
// or a source missing the field its kind needs, refuses the whole kind, as a
98-
// kind with an invalid name schema is refused today.
97+
// or a source missing the field its kind needs, refuses the whole kind.
9998
func Validate(c *cozyv1alpha1.ApplicationDefinitionCredentials) error {
10099
if c == nil {
101100
return nil

0 commit comments

Comments
 (0)