Skip to content

Commit ed6c737

Browse files
andrewkrohandrewkroh
authored
improve godoc coverage (#25)
Add godoc to Field, Manifest, and Var.
1 parent 65acff0 commit ed6c737

File tree

2 files changed

+134
-67
lines changed

2 files changed

+134
-67
lines changed

‎fields.go‎

Lines changed: 41 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -27,38 +27,45 @@ import (
2727
"gopkg.in/yaml.v3"
2828
)
2929

30+
// Field represents an Elasticsearch field definition in the Elastic package
31+
// specification. It contains all the properties that can be used to define how a
32+
// field is mapped, indexed, and used in Elasticsearch.
33+
//
34+
// Field definitions can be nested, with parent fields containing child fields.
35+
// Each field must have a name, and most fields will have a type that determines
36+
// how the field is indexed and stored in Elasticsearch.
3037
type Field struct {
31-
Name string `json:"name,omitempty" yaml:"name,omitempty"`
32-
Type string `json:"type,omitempty" yaml:"type,omitempty"`
33-
Description string `json:"description,omitempty" yaml:"description,omitempty"`
34-
Value string `json:"value,omitempty" yaml:"value,omitempty"`
35-
Example any `json:"example,omitempty" yaml:"example,omitempty"`
36-
MetricType string `json:"metric_type,omitempty" yaml:"metric_type,omitempty"`
37-
Unit string `json:"unit,omitempty" yaml:"unit,omitempty"`
38-
DateFormat string `json:"date_format,omitempty" yaml:"date_format,omitempty"`
39-
Dimension *bool `json:"dimension,omitempty" yaml:"dimension,omitempty"`
40-
Pattern string `json:"pattern,omitempty" yaml:"pattern,omitempty"`
41-
External string `json:"external,omitempty" yaml:"external,omitempty"`
42-
Fields []Field `json:"fields,omitempty" yaml:"fields,omitempty"`
43-
DocValues *bool `json:"doc_values,omitempty" yaml:"doc_values,omitempty"`
44-
Index *bool `json:"index,omitempty" yaml:"index,omitempty"`
45-
CopyTo string `json:"copy_to,omitempty" yaml:"copy_to,omitempty"`
46-
Enabled *bool `json:"enabled,omitempty" yaml:"enabled,omitempty"`
47-
Dynamic string `json:"dynamic,omitempty" yaml:"dynamic,omitempty"`
48-
ScalingFactor *int `json:"scaling_factor,omitempty" yaml:"scaling_factor,omitempty"`
49-
Analyzer string `json:"analyzer,omitempty" yaml:"analyzer,omitempty"`
50-
SearchAnalyzer string `json:"search_analyzer,omitempty" yaml:"search_analyzer,omitempty"`
51-
MultiFields []Field `json:"multi_fields,omitempty" yaml:"multi_fields,omitempty"`
52-
NullValue string `json:"null_value,omitempty" yaml:"null_value,omitempty"`
53-
IgnoreMalformed *bool `json:"ignore_malformed,omitempty" yaml:"ignore_malformed,omitempty"`
54-
IgnoreAbove int `json:"ignore_above,omitempty" yaml:"ignore_above,omitempty"`
55-
ObjectType string `json:"object_type,omitempty" yaml:"object_type,omitempty"`
56-
ObjectTypeMappingType string `json:"object_type_mapping_type,omitempty" yaml:"object_type_mapping_type,omitempty"`
57-
AliasTargetPath string `json:"path,omitempty" yaml:"path,omitempty"`
58-
Normalize []string `json:"normalize,omitempty" yaml:"normalize,omitempty"`
59-
Normalizer string `json:"normalizer,omitempty" yaml:"normalizer,omitempty"`
60-
IncludeInParent *bool `json:"include_in_parent,omitempty" yaml:"include_in_parent,omitempty"`
61-
DefaultMetric string `json:"default_metric,omitempty" yaml:"default_metric,omitempty"`
38+
Name string `json:"name,omitempty" yaml:"name,omitempty"` // Name of the field
39+
Type string `json:"type,omitempty" yaml:"type,omitempty"` // Type of the field as used in Elasticsearch
40+
Description string `json:"description,omitempty" yaml:"description,omitempty"` // Description of the field
41+
Value string `json:"value,omitempty" yaml:"value,omitempty"` // Constant value assigned to this field
42+
Example any `json:"example,omitempty" yaml:"example,omitempty"` // Example value for this field, used in documentation
43+
MetricType string `json:"metric_type,omitempty" yaml:"metric_type,omitempty"` // For metric fields, defines what kind of metric this is
44+
Unit string `json:"unit,omitempty" yaml:"unit,omitempty"` // Unit this field is measured in
45+
DateFormat string `json:"date_format,omitempty" yaml:"date_format,omitempty"` // Format of the date string in this field
46+
Dimension *bool `json:"dimension,omitempty" yaml:"dimension,omitempty"` // Identifies a field to be a dimension for grouping when a metric is associated with multiple dimensions
47+
Pattern string `json:"pattern,omitempty" yaml:"pattern,omitempty"` // Regular expression pattern for validating field values
48+
External string `json:"external,omitempty" yaml:"external,omitempty"` // Identifier for the type of metric when referencing an external schema
49+
Fields []Field `json:"fields,omitempty" yaml:"fields,omitempty"` // Nested fields within this field
50+
DocValues *bool `json:"doc_values,omitempty" yaml:"doc_values,omitempty"` // Controls whether the field is indexed in a column-stride fashion for sorting and aggregations
51+
Index *bool `json:"index,omitempty" yaml:"index,omitempty"` // Controls whether the field will be indexed for full-text search
52+
CopyTo string `json:"copy_to,omitempty" yaml:"copy_to,omitempty"` // Target field to copy this field's values to
53+
Enabled *bool `json:"enabled,omitempty" yaml:"enabled,omitempty"` // Whether mappings are created for this field's children
54+
Dynamic string `json:"dynamic,omitempty" yaml:"dynamic,omitempty"` // Controls whether new fields are added dynamically or ignored if not defined
55+
ScalingFactor *int `json:"scaling_factor,omitempty" yaml:"scaling_factor,omitempty"` // Scaling factor to use for scaled_float type
56+
Analyzer string `json:"analyzer,omitempty" yaml:"analyzer,omitempty"` // Analyzer used for full-text search
57+
SearchAnalyzer string `json:"search_analyzer,omitempty" yaml:"search_analyzer,omitempty"` // Analyzer to use at search time
58+
MultiFields []Field `json:"multi_fields,omitempty" yaml:"multi_fields,omitempty"` // Sub-fields to index the same value in different ways
59+
NullValue string `json:"null_value,omitempty" yaml:"null_value,omitempty"` // Value to replace null with when indexing
60+
IgnoreMalformed *bool `json:"ignore_malformed,omitempty" yaml:"ignore_malformed,omitempty"` // Whether to ignore malformed values in the field
61+
IgnoreAbove int `json:"ignore_above,omitempty" yaml:"ignore_above,omitempty"` // String values longer than this will not be indexed or stored
62+
ObjectType string `json:"object_type,omitempty" yaml:"object_type,omitempty"` // Type of the object field
63+
ObjectTypeMappingType string `json:"object_type_mapping_type,omitempty" yaml:"object_type_mapping_type,omitempty"` // Mapping type for the object field
64+
AliasTargetPath string `json:"path,omitempty" yaml:"path,omitempty"` // For alias type fields this is the path to the target field, including parent objects
65+
Normalize []string `json:"normalize,omitempty" yaml:"normalize,omitempty"` // Specifies the expected normalizations for a field, such as 'array' normalization
66+
Normalizer string `json:"normalizer,omitempty" yaml:"normalizer,omitempty"` // Specifies the name of a normalizer to apply to keyword fields
67+
IncludeInParent *bool `json:"include_in_parent,omitempty" yaml:"include_in_parent,omitempty"` // For nested field types, specifies if fields in the nested object are also added to the parent document
68+
DefaultMetric string `json:"default_metric,omitempty" yaml:"default_metric,omitempty"` // For aggregate_metric_double fields, specifies the default metric aggregation
6269

6370
// AdditionalProperties contains additional properties that are not
6471
// explicitly specified in the package-spec and are not used by Fleet.
@@ -181,10 +188,9 @@ func flattenField(key []string, f Field) ([]Field, error) {
181188
flat = append(flat, tmpFlats...)
182189
}
183190

184-
// I would consider this to be an incorrect definition to
185-
// have sub-fields in a field not declared as a type=group.
186-
// This will include those fields in the list in order to not
187-
// mask bad definitions.
191+
// I would consider this to be an incorrect definition to have sub-fields in
192+
// a field not declared as a type=group. This will include those fields in
193+
// the list to not mask bad definitions.
188194
if f.Type != "" && f.Type != "group" {
189195
parent := f
190196
parent.Name = strings.Join(parentName, ".")

‎fleetpkg.go‎

Lines changed: 93 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -102,28 +102,74 @@ func (f FieldsFile) Path() string {
102102
return f.sourceFile
103103
}
104104

105+
// Manifest represents the manifest.yml file of an integration package
106+
// that provides metadata about the package.
105107
type Manifest struct {
106-
Name string `json:"name,omitempty" yaml:"name,omitempty"`
107-
Title string `json:"title,omitempty" yaml:"title,omitempty"`
108-
Version string `json:"version,omitempty" yaml:"version,omitempty"`
109-
Release string `json:"release,omitempty" yaml:"release,omitempty"`
110-
Description string `json:"description,omitempty" yaml:"description,omitempty"`
111-
Type string `json:"type,omitempty" yaml:"type,omitempty"`
112-
Icons []Icons `json:"icons,omitempty" yaml:"icons,omitempty"`
113-
FormatVersion string `json:"format_version,omitempty" yaml:"format_version,omitempty"`
114-
License string `json:"license,omitempty" yaml:"license,omitempty"`
115-
Categories []string `json:"categories,omitempty" yaml:"categories,omitempty"`
116-
Conditions Conditions `json:"conditions,omitempty" yaml:"conditions,omitempty"`
117-
Screenshots []Screenshots `json:"screenshots,omitempty" yaml:"screenshots,omitempty"`
118-
Source Source `json:"source,omitempty" yaml:"source,omitempty"`
119-
Vars []Var `json:"vars,omitempty" yaml:"vars,omitempty"`
120-
PolicyTemplates []PolicyTemplate `json:"policy_templates,omitempty" yaml:"policy_templates,omitempty"`
121-
PolicyTemplatesBehavior string `json:"policy_templates_behavior,omitempty" yaml:"policy_templates_behavior,omitempty"` // Expected behavior when there are more than one policy template defined.
122-
Owner Owner `json:"owner,omitempty" yaml:"owner,omitempty"`
123-
Elasticsearch *ElasticsearchRequirements `json:"elasticsearch,omitempty" yaml:"elasticsearch,omitempty"`
124-
Agent *AgentRequirements `json:"agent,omitempty" yaml:"agent,omitempty"`
125-
DeploymentModes *DeploymentModes `json:"deployment_modes,omitempty" yaml:"deployment_modes,omitempty"`
126-
Discovery *Discovery `json:"discovery,omitempty" yaml:"discovery,omitempty"`
108+
// Name is the name of the package.
109+
Name string `json:"name,omitempty" yaml:"name,omitempty"`
110+
111+
// Title is the title of the package.
112+
Title string `json:"title,omitempty" yaml:"title,omitempty"`
113+
114+
// Version is the version of the package.
115+
Version string `json:"version,omitempty" yaml:"version,omitempty"`
116+
117+
// Release is the stability of the package (deprecated, use prerelease tags in the version).
118+
Release string `json:"release,omitempty" yaml:"release,omitempty"`
119+
120+
// Description is a description of the package.
121+
Description string `json:"description,omitempty" yaml:"description,omitempty"`
122+
123+
// Type is the type of package (e.g. integration).
124+
Type string `json:"type,omitempty" yaml:"type,omitempty"`
125+
126+
// Icons is a list of icons for the package.
127+
Icons []Icons `json:"icons,omitempty" yaml:"icons,omitempty"`
128+
129+
// FormatVersion is the version of the package format.
130+
FormatVersion string `json:"format_version,omitempty" yaml:"format_version,omitempty"`
131+
132+
// License is the license under which the package is being released (deprecated).
133+
License string `json:"license,omitempty" yaml:"license,omitempty"`
134+
135+
// Categories is a list of categories the package belongs to.
136+
Categories []string `json:"categories,omitempty" yaml:"categories,omitempty"`
137+
138+
// Conditions specifies the conditions under which the package can be used.
139+
Conditions Conditions `json:"conditions,omitempty" yaml:"conditions,omitempty"`
140+
141+
// Screenshots is a list of screenshots for the package.
142+
Screenshots []Screenshots `json:"screenshots,omitempty" yaml:"screenshots,omitempty"`
143+
144+
// Source provides information about the source of the package.
145+
Source Source `json:"source,omitempty" yaml:"source,omitempty"`
146+
147+
// Vars is a list of variables that can be configured for the package.
148+
Vars []Var `json:"vars,omitempty" yaml:"vars,omitempty"`
149+
150+
// PolicyTemplates is a list of policy templates offered by this package.
151+
PolicyTemplates []PolicyTemplate `json:"policy_templates,omitempty" yaml:"policy_templates,omitempty"`
152+
153+
// PolicyTemplatesBehavior specifies the expected behavior when there are more than one policy template defined.
154+
// When set to "combined_policy", a single policy template is available that combines all the defined templates.
155+
// When set to "individual_policies", all policies are individually available, but there is no combined policy.
156+
// The default value is "all", where the combined policy template is available along with the individual policies.
157+
PolicyTemplatesBehavior string `json:"policy_templates_behavior,omitempty" yaml:"policy_templates_behavior,omitempty"`
158+
159+
// Owner provides information about the owner of the package.
160+
Owner Owner `json:"owner,omitempty" yaml:"owner,omitempty"`
161+
162+
// Elasticsearch specifies the Elasticsearch requirements for the package.
163+
Elasticsearch *ElasticsearchRequirements `json:"elasticsearch,omitempty" yaml:"elasticsearch,omitempty"`
164+
165+
// Agent specifies the agent requirements for the package.
166+
Agent *AgentRequirements `json:"agent,omitempty" yaml:"agent,omitempty"`
167+
168+
// DeploymentModes specifies the deployment modes supported by the package.
169+
DeploymentModes *DeploymentModes `json:"deployment_modes,omitempty" yaml:"deployment_modes,omitempty"`
170+
171+
// Discovery provides information about the package discovery capabilities.
172+
Discovery *Discovery `json:"discovery,omitempty" yaml:"discovery,omitempty"`
127173

128174
sourceFile string
129175
}
@@ -218,18 +264,33 @@ type Screenshots struct {
218264
Type string `json:"type,omitempty" yaml:"type,omitempty"`
219265
}
220266

267+
// Var represents an input variable for a package configuration. Variables allow users
268+
// to customize package behavior through the Fleet UI or configuration.
221269
type Var struct {
222-
Name string `json:"name,omitempty" yaml:"name,omitempty"`
223-
Default any `json:"default,omitempty" yaml:"default,omitempty"`
224-
Description string `json:"description,omitempty" yaml:"description,omitempty"`
225-
Type string `json:"type,omitempty" yaml:"type,omitempty"`
226-
Title string `json:"title,omitempty" yaml:"title,omitempty"`
227-
Multi *bool `json:"multi,omitempty" yaml:"multi,omitempty"`
228-
Required *bool `json:"required,omitempty" yaml:"required,omitempty"`
229-
Secret *bool `json:"secret,omitempty" yaml:"secret,omitempty"`
230-
ShowUser *bool `json:"show_user,omitempty" yaml:"show_user,omitempty"`
231-
Options []Option `json:"options,omitempty" yaml:"options,omitempty"` // List of options for 'type: select'.
232-
HideInDeploymentModes []string `json:"hide_in_deployment_modes,omitempty" yaml:"hide_in_deployment_modes,omitempty"` // Whether this variable should be hidden in the UI for agent policies intended to some specific deployment modes.
270+
// Name is the variable name.
271+
Name string `json:"name,omitempty" yaml:"name,omitempty"`
272+
// Default is the default value(s) for the variable.
273+
Default any `json:"default,omitempty" yaml:"default,omitempty"`
274+
// Description is a short description of the variable.
275+
Description string `json:"description,omitempty" yaml:"description,omitempty"`
276+
// Type is the data type of variable (e.g., bool, email, integer, password, select, text, textarea, time_zone, url, yaml).
277+
Type string `json:"type,omitempty" yaml:"type,omitempty"`
278+
// Title is the title of the variable displayed in the UI.
279+
Title string `json:"title,omitempty" yaml:"title,omitempty"`
280+
// Multi specifies if the variable can contain multiple values.
281+
Multi *bool `json:"multi,omitempty" yaml:"multi,omitempty"`
282+
// Required specifies if the variable is required.
283+
Required *bool `json:"required,omitempty" yaml:"required,omitempty"`
284+
// Secret indicates that the variable contains sensitive information that should be stored securely.
285+
// Secret variables are write-only; once set, users cannot read them again, only overwrite them.
286+
Secret *bool `json:"secret,omitempty" yaml:"secret,omitempty"`
287+
// ShowUser indicates whether this variable should be shown to the user by default.
288+
ShowUser *bool `json:"show_user,omitempty" yaml:"show_user,omitempty"`
289+
// Options is a list of options for variables of type 'select'.
290+
Options []Option `json:"options,omitempty" yaml:"options,omitempty"`
291+
// HideInDeploymentModes specifies whether this variable should be hidden in the UI
292+
// for agent policies intended for specific deployment modes.
293+
HideInDeploymentModes []string `json:"hide_in_deployment_modes,omitempty" yaml:"hide_in_deployment_modes,omitempty"`
233294

234295
FileMetadata `json:"-" yaml:"-"`
235296
}

0 commit comments

Comments
 (0)