Skip to content

Commit d6ebe51

Browse files
spoltiricardozanini
spolti
and
ricardozanini
authored
Add kubebuilder annotations and fix model descriptions (#160)
* temo Signed-off-by: Spolti <filippespolti@gmail.com> * Include kubebuilder validation annotations Signed-off-by: Spolti <filippespolti@gmail.com> * review suggestions Signed-off-by: Spolti <filippespolti@gmail.com> * review suggestions Signed-off-by: Spolti <filippespolti@gmail.com> * review additions Signed-off-by: Spolti <filippespolti@gmail.com> * Update model/function.go Co-authored-by: Ricardo Zanini <1538000+ricardozanini@users.noreply.github.com> Signed-off-by: Spolti <filippespolti@gmail.com> --------- Signed-off-by: Spolti <filippespolti@gmail.com> Co-authored-by: Ricardo Zanini <1538000+ricardozanini@users.noreply.github.com>
1 parent 6a4e16c commit d6ebe51

22 files changed

+517
-219
lines changed

‎model/action.go

Lines changed: 42 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -22,27 +22,43 @@ import (
2222

2323
// Action specify invocations of services or other workflows during workflow execution.
2424
type Action struct {
25-
// ID defines Unique action identifier
25+
// Defines Unique action identifier.
26+
// +optional
2627
ID string `json:"id,omitempty"`
27-
// Name defines Unique action definition name
28+
// Defines Unique action name.
29+
// +optional
2830
Name string `json:"name,omitempty"`
29-
// FunctionRef references a reusable function definition
31+
// References a reusable function definition.
32+
// +optional
3033
FunctionRef *FunctionRef `json:"functionRef,omitempty"`
31-
// EventRef references a 'trigger' and 'result' reusable event definitions
34+
// References a 'trigger' and 'result' reusable event definitions.
35+
// +optional
3236
EventRef *EventRef `json:"eventRef,omitempty"`
33-
// References a sub-workflow to be executed
37+
// References a workflow to be invoked.
38+
// +optional
3439
SubFlowRef *WorkflowRef `json:"subFlowRef,omitempty"`
35-
// Sleep Defines time period workflow execution should sleep before / after function execution
40+
// Defines time period workflow execution should sleep before / after function execution.
41+
// +optional
3642
Sleep *Sleep `json:"sleep,omitempty"`
37-
// RetryRef References a defined workflow retry definition. If not defined the default retry policy is assumed
43+
// References a defined workflow retry definition. If not defined uses the default runtime retry definition.
44+
// +optional
3845
RetryRef string `json:"retryRef,omitempty"`
39-
// List of unique references to defined workflow errors for which the action should not be retried. Used only when `autoRetries` is set to `true`
46+
// List of unique references to defined workflow errors for which the action should not be retried.
47+
// Used only when `autoRetries` is set to `true`
48+
// +optional
4049
NonRetryableErrors []string `json:"nonRetryableErrors,omitempty" validate:"omitempty,min=1"`
41-
// List of unique references to defined workflow errors for which the action should be retried. Used only when `autoRetries` is set to `false`
50+
// List of unique references to defined workflow errors for which the action should be retried.
51+
// Used only when `autoRetries` is set to `false`
52+
// +optional
4253
RetryableErrors []string `json:"retryableErrors,omitempty" validate:"omitempty,min=1"`
43-
// Action data filter
54+
// Filter the state data to select only the data that can be used within function definition arguments
55+
// using its fromStateData property. Filter the action results to select only the result data that should
56+
// be added/merged back into the state data using its results property. Select the part of state data which
57+
// the action data results should be added/merged to using the toStateData property.
58+
// +optional
4459
ActionDataFilter ActionDataFilter `json:"actionDataFilter,omitempty"`
45-
// Workflow expression evaluated against state data. Must evaluate to true or false
60+
// Expression, if defined, must evaluate to true for this action to be performed. If false, action is disregarded.
61+
// +optional
4662
Condition string `json:"condition,omitempty"`
4763
}
4864

@@ -65,16 +81,20 @@ func (a *Action) UnmarshalJSON(data []byte) error {
6581

6682
// FunctionRef defines the reference to a reusable function definition
6783
type FunctionRef struct {
68-
// Name of the referenced function
84+
// Name of the referenced function.
85+
// +kubebuilder:validation:Required
6986
RefName string `json:"refName" validate:"required"`
70-
// Function arguments
87+
// Arguments (inputs) to be passed to the referenced function
88+
// +optional
7189
// TODO: validate it as required if function type is graphql
7290
Arguments map[string]Object `json:"arguments,omitempty"`
73-
// String containing a valid GraphQL selection set
91+
// Used if function type is graphql. String containing a valid GraphQL selection set.
7492
// TODO: validate it as required if function type is graphql
93+
// +optional
7594
SelectionSet string `json:"selectionSet,omitempty"`
76-
// Invoke specifies if the subflow should be invoked sync or async.
77-
// Defaults to sync.
95+
// Specifies if the function should be invoked sync or async. Default is sync.
96+
// +kubebuilder:validation:Enum=async;sync
97+
// +kubebuilder:default=sync
7898
Invoke InvokeKind `json:"invoke,omitempty" validate:"required,oneof=async sync"`
7999
}
80100

@@ -113,8 +133,12 @@ func (f *FunctionRef) UnmarshalJSON(data []byte) error {
113133

114134
// Sleep defines time periods workflow execution should sleep before & after function execution
115135
type Sleep struct {
116-
// Before defines amount of time (ISO 8601 duration format) to sleep before function/subflow invocation. Does not apply if 'eventRef' is defined.
136+
// Defines amount of time (ISO 8601 duration format) to sleep before function/subflow invocation.
137+
// Does not apply if 'eventRef' is defined.
138+
// +optional
117139
Before string `json:"before,omitempty" validate:"omitempty,iso8601duration"`
118-
// After defines amount of time (ISO 8601 duration format) to sleep after function/subflow invocation. Does not apply if 'eventRef' is defined.
140+
// Defines amount of time (ISO 8601 duration format) to sleep after function/subflow invocation.
141+
// Does not apply if 'eventRef' is defined.
142+
// +optional
119143
After string `json:"after,omitempty" validate:"omitempty,iso8601duration"`
120144
}

‎model/action_data_filter.go

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -21,17 +21,23 @@ import (
2121
)
2222

2323
// ActionDataFilter used to filter action data results.
24+
// +optional
25+
// +optional
2426
type ActionDataFilter struct {
25-
// Workflow expression that selects state data that the state action can use
27+
// Workflow expression that filters state data that can be used by the action.
28+
// +optional
29+
// +optional
2630
FromStateData string `json:"fromStateData,omitempty"`
27-
28-
// UseResults represent where action data results is added/merged to state data. If it's false, results & toStateData should be ignored.
29-
// Defaults to true.
31+
// If set to false, action data results are not added/merged to state data. In this case 'results'
32+
// and 'toStateData' should be ignored. Default is true.
33+
// +optional
3034
UseResults bool `json:"useResults,omitempty"`
31-
32-
// Workflow expression that filters the actions' data results
35+
// Workflow expression that filters the actions data results.
36+
// +optional
3337
Results string `json:"results,omitempty"`
34-
// Workflow expression that selects a state data element to which the action results should be added/merged into. If not specified, denote, the top-level state data element
38+
// Workflow expression that selects a state data element to which the action results should be
39+
// added/merged into. If not specified denotes the top-level state data element.
40+
// +optional
3541
ToStateData string `json:"toStateData,omitempty"`
3642
}
3743

‎model/auth.go

Lines changed: 44 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ import (
2020
"strings"
2121
)
2222

23-
// AuthType ...
23+
// AuthType can be "basic", "bearer", or "oauth2". Default is "basic"
2424
type AuthType string
2525

2626
const (
@@ -44,13 +44,21 @@ const (
4444
GrantTypeTokenExchange GrantType = "tokenExchange"
4545
)
4646

47-
// Auth ...
47+
// Auth definitions can be used to define authentication information that should be applied to resources
48+
// defined in the operation property of function definitions. It is not used as authentication information
49+
// for the function invocation, but just to access the resource containing the function invocation information.
4850
type Auth struct {
49-
// Name Unique auth definition name
51+
// Unique auth definition name.
52+
// +kubebuilder:validation:Required
5053
Name string `json:"name" validate:"required"`
51-
// Scheme Defines the auth type
52-
Scheme AuthType `json:"scheme,omitempty" validate:"omitempty,min=1"`
53-
// Properties ...
54+
// Auth scheme, can be "basic", "bearer", or "oauth2". Default is "basic"
55+
// +kubebuilder:validation:Enum=basic;bearer;oauth2
56+
// +kubebuilder:default=basic
57+
// +kubebuilder:validation:Required
58+
Scheme AuthType `json:"scheme" validate:"min=1"`
59+
// Auth scheme properties. Can be one of "Basic properties definition", "Bearer properties definition",
60+
// or "OAuth2 properties definition"
61+
// +kubebuilder:validation:Required
5462
Properties AuthProperties `json:"properties" validate:"required"`
5563
}
5664

@@ -145,10 +153,13 @@ type AuthProperties struct {
145153
type BasicAuthProperties struct {
146154
Common `json:",inline"`
147155
// Secret Expression referencing a workflow secret that contains all needed auth info
156+
// +optional
148157
Secret string `json:"secret,omitempty"`
149158
// Username String or a workflow expression. Contains the username
159+
// +kubebuilder:validation:Required
150160
Username string `json:"username" validate:"required"`
151161
// Password String or a workflow expression. Contains the user password
162+
// +kubebuilder:validation:Required
152163
Password string `json:"password" validate:"required"`
153164
}
154165

@@ -177,8 +188,10 @@ func (b *BasicAuthProperties) UnmarshalJSON(data []byte) error {
177188
type BearerAuthProperties struct {
178189
Common `json:",inline"`
179190
// Secret Expression referencing a workflow secret that contains all needed auth info
191+
// +optional
180192
Secret string `json:"secret,omitempty"`
181193
// Token String or a workflow expression. Contains the token
194+
// +kubebuilder:validation:Required
182195
Token string `json:"token" validate:"required"`
183196
}
184197

@@ -203,29 +216,42 @@ func (b *BearerAuthProperties) UnmarshalJSON(data []byte) error {
203216
// OAuth2AuthProperties OAuth2 information
204217
type OAuth2AuthProperties struct {
205218
Common `json:",inline"`
206-
// Secret Expression referencing a workflow secret that contains all needed auth info
219+
// Expression referencing a workflow secret that contains all needed auth info.
220+
// +optional
207221
Secret string `json:"secret,omitempty"`
208-
// Authority String or a workflow expression. Contains the authority information
222+
// String or a workflow expression. Contains the authority information.
223+
// +optional
209224
Authority string `json:"authority,omitempty" validate:"omitempty,min=1"`
210-
// GrantType Defines the grant type
225+
// Defines the grant type. Can be "password", "clientCredentials", or "tokenExchange"
226+
// +kubebuilder:validation:Enum=password;clientCredentials;tokenExchange
227+
// +kubebuilder:validation:Required
211228
GrantType GrantType `json:"grantType" validate:"required"`
212-
// ClientID String or a workflow expression. Contains the client identifier
229+
// String or a workflow expression. Contains the client identifier.
230+
// +kubebuilder:validation:Required
213231
ClientID string `json:"clientId" validate:"required"`
214-
// ClientSecret Workflow secret or a workflow expression. Contains the client secret
232+
// Workflow secret or a workflow expression. Contains the client secret.
233+
// +optional
215234
ClientSecret string `json:"clientSecret,omitempty" validate:"omitempty,min=1"`
216-
// Scopes Array containing strings or workflow expressions. Contains the OAuth2 scopes
235+
// Array containing strings or workflow expressions. Contains the OAuth2 scopes.
236+
// +optional
217237
Scopes []string `json:"scopes,omitempty" validate:"omitempty,min=1"`
218-
// Username String or a workflow expression. Contains the username. Used only if grantType is 'resourceOwner'
238+
// String or a workflow expression. Contains the username. Used only if grantType is 'resourceOwner'.
239+
// +optional
219240
Username string `json:"username,omitempty" validate:"omitempty,min=1"`
220-
// Password String or a workflow expression. Contains the user password. Used only if grantType is 'resourceOwner'
241+
// String or a workflow expression. Contains the user password. Used only if grantType is 'resourceOwner'.
242+
// +optional
221243
Password string `json:"password,omitempty" validate:"omitempty,min=1"`
222-
// Audiences Array containing strings or workflow expressions. Contains the OAuth2 audiences
244+
// Array containing strings or workflow expressions. Contains the OAuth2 audiences.
245+
// +optional
223246
Audiences []string `json:"audiences,omitempty" validate:"omitempty,min=1"`
224-
// SubjectToken String or a workflow expression. Contains the subject token
247+
// String or a workflow expression. Contains the subject token.
248+
// +optional
225249
SubjectToken string `json:"subjectToken,omitempty" validate:"omitempty,min=1"`
226-
// RequestedSubject String or a workflow expression. Contains the requested subject
250+
// String or a workflow expression. Contains the requested subject.
251+
// +optional
227252
RequestedSubject string `json:"requestedSubject,omitempty" validate:"omitempty,min=1"`
228-
// RequestedIssuer String or a workflow expression. Contains the requested issuer
253+
// String or a workflow expression. Contains the requested issuer.
254+
// +optional
229255
RequestedIssuer string `json:"requestedIssuer,omitempty" validate:"omitempty,min=1"`
230256
}
231257

‎model/callback_state.go

Lines changed: 17 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -18,16 +18,19 @@ import (
1818
"encoding/json"
1919
)
2020

21-
// CallbackState executes a function and waits for callback event that indicates
22-
// completion of the task.
21+
// CallbackState executes a function and waits for callback event that indicates completion of the task.
2322
type CallbackState struct {
24-
// Defines the action to be executed
23+
// Defines the action to be executed.
24+
// +kubebuilder:validation:Required
2525
Action Action `json:"action" validate:"required"`
26-
// References a unique callback event name in the defined workflow events
26+
// References a unique callback event name in the defined workflow events.
27+
// +kubebuilder:validation:Required
2728
EventRef string `json:"eventRef" validate:"required"`
2829
// Time period to wait for incoming events (ISO 8601 format)
30+
// +optional
2931
Timeouts *CallbackStateTimeout `json:"timeouts,omitempty"`
30-
// Event data filter
32+
// Event data filter definition.
33+
// +optional
3134
EventDataFilter *EventDataFilter `json:"eventDataFilter,omitempty"`
3235
}
3336

@@ -45,7 +48,13 @@ func (c *CallbackState) MarshalJSON() ([]byte, error) {
4548

4649
// CallbackStateTimeout defines timeout settings for callback state
4750
type CallbackStateTimeout struct {
48-
StateExecTimeout *StateExecTimeout `json:"stateExecTimeout,omitempty"`
49-
ActionExecTimeout string `json:"actionExecTimeout,omitempty" validate:"omitempty,iso8601duration"`
50-
EventTimeout string `json:"eventTimeout,omitempty" validate:"omitempty,iso8601duration"`
51+
// Default workflow state execution timeout (ISO 8601 duration format)
52+
// +optional
53+
StateExecTimeout *StateExecTimeout `json:"stateExecTimeout,omitempty"`
54+
// Default single actions definition execution timeout (ISO 8601 duration format)
55+
// +optional
56+
ActionExecTimeout string `json:"actionExecTimeout,omitempty" validate:"omitempty,iso8601duration"`
57+
// Default timeout for consuming defined events (ISO 8601 duration format)
58+
// +optional
59+
EventTimeout string `json:"eventTimeout,omitempty" validate:"omitempty,iso8601duration"`
5160
}

‎model/common.go

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ package model
1717
// Common schema for Serverless Workflow specification
1818
type Common struct {
1919
// Metadata information
20+
// +optional
2021
Metadata Metadata `json:"metadata,omitempty"`
2122
}
2223

‎model/delay_state.go

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ import "encoding/json"
1919
// DelayState Causes the workflow execution to delay for a specified duration
2020
type DelayState struct {
2121
// Amount of time (ISO 8601 format) to delay
22+
// +kubebuilder:validation:Required
2223
TimeDelay string `json:"timeDelay" validate:"required,iso8601duration"`
2324
}
2425

‎model/event.go

Lines changed: 31 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -32,19 +32,25 @@ const (
3232
// Event used to define events and their correlations
3333
type Event struct {
3434
Common `json:",inline"`
35-
// Unique event name
35+
// Unique event name.
36+
// +kubebuilder:validation:Required
3637
Name string `json:"name" validate:"required"`
37-
// CloudEvent source
38+
// CloudEvent source.
39+
// +optional
3840
Source string `json:"source,omitempty"`
39-
// CloudEvent type
41+
// CloudEvent type.
42+
// +kubebuilder:validation:Required
4043
Type string `json:"type" validate:"required"`
41-
// Defines the CloudEvent as either 'consumed' or 'produced' by the workflow.
42-
// Defaults to `consumed`
44+
// Defines the CloudEvent as either 'consumed' or 'produced' by the workflow. Defaults to `consumed`.
45+
// +kubebuilder:validation:Enum=consumed;produced
46+
// +kubebuilder:default=consumed
4347
Kind EventKind `json:"kind,omitempty"`
44-
// If `true`, only the Event payload is accessible to consuming Workflow states. If `false`, both event payload and context attributes should be accessible"
45-
// Defaults to true
48+
// If `true`, only the Event payload is accessible to consuming Workflow states. If `false`, both event payload
49+
// and context attributes should be accessible. Defaults to true.
50+
// +optional
4651
DataOnly bool `json:"dataOnly,omitempty"`
47-
// CloudEvent correlation definitions
52+
// Define event correlation rules for this event. Only used for consumed events.
53+
// +optional
4854
Correlation []Correlation `json:"correlation,omitempty" validate:"omitempty,dive"`
4955
}
5056

@@ -68,26 +74,36 @@ func (e *Event) UnmarshalJSON(data []byte) error {
6874
// Correlation define event correlation rules for an event. Only used for `consumed` events
6975
type Correlation struct {
7076
// CloudEvent Extension Context Attribute name
77+
// +kubebuilder:validation:Required
7178
ContextAttributeName string `json:"contextAttributeName" validate:"required"`
7279
// CloudEvent Extension Context Attribute value
80+
// +optional
7381
ContextAttributeValue string `json:"contextAttributeValue,omitempty"`
7482
}
7583

7684
// EventRef defining invocation of a function via event
7785
type EventRef struct {
78-
// Reference to the unique name of a 'produced' event definition
86+
// Reference to the unique name of a 'produced' event definition,
87+
// +kubebuilder:validation:Required
7988
TriggerEventRef string `json:"triggerEventRef" validate:"required"`
8089
// Reference to the unique name of a 'consumed' event definition
90+
// +kubebuilder:validation:Required
8191
ResultEventRef string `json:"resultEventRef" validate:"required"`
82-
// ResultEventTimeout defines maximum amount of time (ISO 8601 format) to wait for the result event. If not defined it be set to the actionExecutionTimeout
92+
// Maximum amount of time (ISO 8601 format) to wait for the result event. If not defined it be set to the
93+
// actionExecutionTimeout
94+
// +optional
8395
ResultEventTimeout string `json:"resultEventTimeout,omitempty" validate:"omitempty,iso8601duration"`
84-
// If string type, an expression which selects parts of the states data output to become the data (payload) of the event referenced by 'triggerEventRef'.
85-
// If object type, a custom object to become the data (payload) of the event referenced by 'triggerEventRef'.
96+
// If string type, an expression which selects parts of the states data output to become the data (payload)
97+
// of the event referenced by triggerEventRef. If object type, a custom object to become the data (payload)
98+
// of the event referenced by triggerEventRef.
99+
// +optional
86100
Data *Object `json:"data,omitempty"`
87-
// Add additional extension context attributes to the produced event
101+
// Add additional extension context attributes to the produced event.
102+
// +optional
88103
ContextAttributes map[string]Object `json:"contextAttributes,omitempty"`
89-
// Invoke specifies if the subflow should be invoked sync or async.
90-
// Defaults to sync.
104+
// Specifies if the function should be invoked sync or async. Default is sync.
105+
// +kubebuilder:validation:Enum=async;sync
106+
// +kubebuilder:default=sync
91107
Invoke InvokeKind `json:"invoke,omitempty" validate:"required,oneof=async sync"`
92108
}
93109

0 commit comments

Comments
 (0)