You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
chore(docs): Refactor configuration requirements and descriptions
- Updated the required status of several configuration fields in the Config struct to improve clarity and flexibility.
- Adjusted descriptions for various fields to provide clearer guidance on their usage and requirements.
- Removed default values from descriptions where applicable to avoid confusion.
- Ensured consistency in required fields across different configuration types, including Redis, MQ, and Portal configurations.
- Enhanced webhook and AWS Kinesis configurations by refining descriptions and removing unnecessary defaults.
Copy file name to clipboardExpand all lines: cmd/configdocsgen/main.go
+27-13Lines changed: 27 additions & 13 deletions
Original file line number
Diff line number
Diff line change
@@ -1,3 +1,7 @@
1
+
// Known Limitations/Further Improvements:
2
+
// Embedded Structs (AST): Fields from anonymously embedded structs are not fully resolved during AST parsing for documentation as part of the parent struct.
3
+
// Complex Slice/Map YAML Formatting: Default value formatting for slices is basic. Maps are not explicitly formatted for YAML beyond their default string representation.
4
+
1
5
package main
2
6
3
7
import (
@@ -58,22 +62,22 @@ func main() {
58
62
log.Printf("Found config struct: %s in file %s", cfg.Name, cfg.FileName)
59
63
}
60
64
61
-
err=generateDocs(parsedConfigs, outputFile) // Corrected: use outputFile
62
-
iferr!=nil {
63
-
log.Fatalf("Error generating docs: %v", err)
64
-
}
65
-
66
-
// Attempt to get and print default values
67
-
// This is a preliminary step to verify type loading and reflection.
65
+
// Attempt to get default values and integrate them BEFORE generating docs
68
66
log.Println("Attempting to load and reflect on config.Config for default values...")
69
67
defaults, err:=getConfigDefaults()
70
68
iferr!=nil {
71
69
log.Printf("Warning: Could not get config defaults: %v", err)
72
-
log.Println("Default values will be missing from the generated documentation.")
70
+
log.Println("Default values will be missing or incorrect in the generated documentation.")
73
71
} else {
74
72
log.Printf("Successfully reflected on config.Config. Total default keys found: %d", len(defaults))
75
73
// Integrate defaults into parsedConfigs
76
-
integrateDefaults(parsedConfigs, defaults) // Call the integration function
74
+
integrateDefaults(parsedConfigs, defaults) // This modifies parsedConfigs in place
75
+
}
76
+
77
+
// Now generate docs with populated defaults
78
+
err=generateDocs(parsedConfigs, outputFile)
79
+
iferr!=nil {
80
+
log.Fatalf("Error generating docs: %v", err)
77
81
}
78
82
79
83
fmt.Printf("Successfully generated documentation to %s\n", outputFile)
Copy file name to clipboardExpand all lines: internal/config/config.go
+20-16Lines changed: 20 additions & 16 deletions
Original file line number
Diff line number
Diff line change
@@ -41,21 +41,21 @@ type Config struct {
41
41
configPathstring// stores the path of the config file used
42
42
43
43
Servicestring`yaml:"service" env:"SERVICE" desc:"Specifies the service type to run. Valid values: 'api', 'log', 'delivery', or empty/all for singular mode (runs all services)." required:"N"`
44
-
LogLevelstring`yaml:"log_level" env:"LOG_LEVEL" desc:"Defines the verbosity of application logs. Common values: 'trace', 'debug', 'info', 'warn', 'error'." required:"Y"`
45
-
AuditLogbool`yaml:"audit_log" env:"AUDIT_LOG" desc:"Enables or disables audit logging for significant events." required:"Y"`
44
+
LogLevelstring`yaml:"log_level" env:"LOG_LEVEL" desc:"Defines the verbosity of application logs. Common values: 'trace', 'debug', 'info', 'warn', 'error'." required:"N"`
45
+
AuditLogbool`yaml:"audit_log" env:"AUDIT_LOG" desc:"Enables or disables audit logging for significant events." required:"N"`
46
46
OpenTelemetryOpenTelemetryConfig`yaml:"otel"`
47
47
TelemetryTelemetryConfig`yaml:"telemetry"`
48
48
49
49
// API
50
-
APIPortint`yaml:"api_port" env:"API_PORT" desc:"Port number for the API server to listen on." required:"Y"`
50
+
APIPortint`yaml:"api_port" env:"API_PORT" desc:"Port number for the API server to listen on." required:"N"`
51
51
APIKeystring`yaml:"api_key" env:"API_KEY" desc:"API key for authenticating requests to the Outpost API." required:"Y"`
52
-
APIJWTSecretstring`yaml:"api_jwt_secret" env:"API_JWT_SECRET" desc:"Secret key for signing and verifying JWTs if JWT authentication is used for the API. Required only if JWT authentication is enabled for the API." required:"C"`
52
+
APIJWTSecretstring`yaml:"api_jwt_secret" env:"API_JWT_SECRET" desc:"Secret key for signing and verifying JWTs if JWT authentication is used for the API." required:"Y"`
53
53
GinModestring`yaml:"gin_mode" env:"GIN_MODE" desc:"Sets the Gin framework mode (e.g., 'debug', 'release', 'test'). See Gin documentation for details." required:"N"`
54
54
55
55
// Application
56
56
AESEncryptionSecretstring`yaml:"aes_encryption_secret" env:"AES_ENCRYPTION_SECRET" desc:"A 16, 24, or 32 byte secret key used for AES encryption of sensitive data at rest." required:"Y"`
57
57
Topics []string`yaml:"topics" env:"TOPICS" envSeparator:"," desc:"Comma-separated list of topics that this Outpost instance should subscribe to for event processing." required:"N"`
58
-
OrganizationNamestring`yaml:"organization_name" env:"ORGANIZATION_NAME" desc:"Name of the organization, used for display purposes and potentially in user agent strings." required:"Y"`
58
+
OrganizationNamestring`yaml:"organization_name" env:"ORGANIZATION_NAME" desc:"Name of the organization, used for display purposes and potentially in user agent strings." required:"N"`
59
59
HTTPUserAgentstring`yaml:"http_user_agent" env:"HTTP_USER_AGENT" desc:"Custom HTTP User-Agent string for outgoing webhook deliveries. If unset, a default (OrganizationName/Version) is used." required:"N"`
60
60
61
61
// Infrastructure
@@ -69,23 +69,23 @@ type Config struct {
69
69
70
70
// Consumers
71
71
PublishMaxConcurrencyint`yaml:"publish_max_concurrency" env:"PUBLISH_MAX_CONCURRENCY" desc:"Maximum number of messages to process concurrently from the publish queue." required:"N"`
72
-
DeliveryMaxConcurrencyint`yaml:"delivery_max_concurrency" env:"DELIVERY_MAX_CONCURRENCY" desc:"Maximum number of delivery attempts to process concurrently." required:"Y"`
73
-
LogMaxConcurrencyint`yaml:"log_max_concurrency" env:"LOG_MAX_CONCURRENCY" desc:"Maximum number of log writing operations to process concurrently." required:"Y"`
72
+
DeliveryMaxConcurrencyint`yaml:"delivery_max_concurrency" env:"DELIVERY_MAX_CONCURRENCY" desc:"Maximum number of delivery attempts to process concurrently." required:"N"`
73
+
LogMaxConcurrencyint`yaml:"log_max_concurrency" env:"LOG_MAX_CONCURRENCY" desc:"Maximum number of log writing operations to process concurrently." required:"N"`
74
74
75
75
// Delivery Retry
76
-
RetryIntervalSecondsint`yaml:"retry_interval_seconds" env:"RETRY_INTERVAL_SECONDS" desc:"Interval in seconds between delivery retry attempts for failed webhooks." required:"Y"`
77
-
RetryMaxLimitint`yaml:"retry_max_limit" env:"MAX_RETRY_LIMIT" desc:"Maximum number of retry attempts for a single event delivery before giving up." required:"Y"`
76
+
RetryIntervalSecondsint`yaml:"retry_interval_seconds" env:"RETRY_INTERVAL_SECONDS" desc:"Interval in seconds between delivery retry attempts for failed webhooks." required:"N"`
77
+
RetryMaxLimitint`yaml:"retry_max_limit" env:"MAX_RETRY_LIMIT" desc:"Maximum number of retry attempts for a single event delivery before giving up." required:"N"`
78
78
79
79
// Event Delivery
80
-
MaxDestinationsPerTenantint`yaml:"max_destinations_per_tenant" env:"MAX_DESTINATIONS_PER_TENANT" desc:"Maximum number of destinations allowed per tenant/organization." required:"Y"`
81
-
DeliveryTimeoutSecondsint`yaml:"delivery_timeout_seconds" env:"DELIVERY_TIMEOUT_SECONDS" desc:"Timeout in seconds for HTTP requests made during event delivery to webhook destinations." required:"Y"`
80
+
MaxDestinationsPerTenantint`yaml:"max_destinations_per_tenant" env:"MAX_DESTINATIONS_PER_TENANT" desc:"Maximum number of destinations allowed per tenant/organization." required:"N"`
81
+
DeliveryTimeoutSecondsint`yaml:"delivery_timeout_seconds" env:"DELIVERY_TIMEOUT_SECONDS" desc:"Timeout in seconds for HTTP requests made during event delivery to webhook destinations." required:"N"`
82
82
83
83
// Destination Registry
84
84
DestinationMetadataPathstring`yaml:"destination_metadata_path" env:"DESTINATION_METADATA_PATH" desc:"Path to the directory containing custom destination type definitions. Overrides 'destinations.metadata_path' if set." required:"N"`
85
85
86
86
// Log batcher configuration
87
-
LogBatchThresholdSecondsint`yaml:"log_batch_threshold_seconds" env:"LOG_BATCH_THRESHOLD_SECONDS" desc:"Maximum time in seconds to buffer logs before flushing them to storage, if batch size is not reached." required:"Y"`
88
-
LogBatchSizeint`yaml:"log_batch_size" env:"LOG_BATCH_SIZE" desc:"Maximum number of log entries to batch together before writing to storage." required:"Y"`
87
+
LogBatchThresholdSecondsint`yaml:"log_batch_threshold_seconds" env:"LOG_BATCH_THRESHOLD_SECONDS" desc:"Maximum time in seconds to buffer logs before flushing them to storage, if batch size is not reached." required:"N"`
88
+
LogBatchSizeint`yaml:"log_batch_size" env:"LOG_BATCH_SIZE" desc:"Maximum number of log entries to batch together before writing to storage." required:"N"`
89
89
90
90
DisableTelemetrybool`yaml:"disable_telemetry" env:"DISABLE_TELEMETRY" desc:"Global flag to disable all telemetry (anonymous usage statistics to Hookdeck and error reporting to Sentry). If true, overrides 'telemetry.disabled'." required:"N"`
Copy file name to clipboardExpand all lines: internal/config/destinations.go
+11-11Lines changed: 11 additions & 11 deletions
Original file line number
Diff line number
Diff line change
@@ -9,7 +9,7 @@ import (
9
9
10
10
// DestinationsConfig is the main configuration for all destination types
11
11
typeDestinationsConfigstruct {
12
-
MetadataPathstring`yaml:"metadata_path" env:"DESTINATIONS_METADATA_PATH" desc:"Path to the directory containing custom destination type definitions. If not set, defaults to 'config/outpost/destinations' as per InitDefaults. This can be overridden by the root-level 'destination_metadata_path' if also set." required:"N"`
12
+
MetadataPathstring`yaml:"metadata_path" env:"DESTINATIONS_METADATA_PATH" desc:"Path to the directory containing custom destination type definitions. This can be overridden by the root-level 'destination_metadata_path' if also set." required:"N"`
13
13
WebhookDestinationWebhookConfig`yaml:"webhook" desc:"Configuration specific to webhook destinations."`
14
14
AWSKinesisDestinationAWSKinesisConfig`yaml:"aws_kinesis" desc:"Configuration specific to AWS Kinesis destinations."`
HeaderPrefixstring`yaml:"header_prefix" env:"DESTINATIONS_WEBHOOK_HEADER_PREFIX" desc:"Prefix for custom headers added to webhook requests (e.g., 'X-MyOrg-'). Defaults to 'x-outpost-'." required:"N"`
37
-
DisableDefaultEventIDHeaderbool`yaml:"disable_default_event_id_header" env:"DESTINATIONS_WEBHOOK_DISABLE_DEFAULT_EVENT_ID_HEADER" desc:"If true, disables adding the default 'X-Outpost-Event-Id' header to webhook requests. Defaults to false." required:"N"`
38
-
DisableDefaultSignatureHeaderbool`yaml:"disable_default_signature_header" env:"DESTINATIONS_WEBHOOK_DISABLE_DEFAULT_SIGNATURE_HEADER" desc:"If true, disables adding the default 'X-Outpost-Signature' header to webhook requests. Defaults to false." required:"N"`
39
-
DisableDefaultTimestampHeaderbool`yaml:"disable_default_timestamp_header" env:"DESTINATIONS_WEBHOOK_DISABLE_DEFAULT_TIMESTAMP_HEADER" desc:"If true, disables adding the default 'X-Outpost-Timestamp' header to webhook requests. Defaults to false." required:"N"`
40
-
DisableDefaultTopicHeaderbool`yaml:"disable_default_topic_header" env:"DESTINATIONS_WEBHOOK_DISABLE_DEFAULT_TOPIC_HEADER" desc:"If true, disables adding the default 'X-Outpost-Topic' header to webhook requests. Defaults to false." required:"N"`
41
-
SignatureContentTemplatestring`yaml:"signature_content_template" env:"DESTINATIONS_WEBHOOK_SIGNATURE_CONTENT_TEMPLATE" desc:"Go template for constructing the content to be signed for webhook requests. Defaults to '{{.Timestamp.Unix}}.{{.Body}}'." required:"N"`
42
-
SignatureHeaderTemplatestring`yaml:"signature_header_template" env:"DESTINATIONS_WEBHOOK_SIGNATURE_HEADER_TEMPLATE" desc:"Go template for the value of the signature header. Defaults to 't={{.Timestamp.Unix}},v0={{.Signatures | join \",\"}}'." required:"N"`
43
-
SignatureEncodingstring`yaml:"signature_encoding" env:"DESTINATIONS_WEBHOOK_SIGNATURE_ENCODING" desc:"Encoding for the signature (e.g., 'hex', 'base64'). Defaults to 'hex'." required:"N"`
44
-
SignatureAlgorithmstring`yaml:"signature_algorithm" env:"DESTINATIONS_WEBHOOK_SIGNATURE_ALGORITHM" desc:"Algorithm used for signing webhook requests (e.g., 'hmac-sha256'). Defaults to 'hmac-sha256'." required:"N"`
36
+
HeaderPrefixstring`yaml:"header_prefix" env:"DESTINATIONS_WEBHOOK_HEADER_PREFIX" desc:"Prefix for custom headers added to webhook requests (e.g., 'X-MyOrg-')." required:"N"`
37
+
DisableDefaultEventIDHeaderbool`yaml:"disable_default_event_id_header" env:"DESTINATIONS_WEBHOOK_DISABLE_DEFAULT_EVENT_ID_HEADER" desc:"If true, disables adding the default 'X-Outpost-Event-Id' header to webhook requests." required:"N"`
38
+
DisableDefaultSignatureHeaderbool`yaml:"disable_default_signature_header" env:"DESTINATIONS_WEBHOOK_DISABLE_DEFAULT_SIGNATURE_HEADER" desc:"If true, disables adding the default 'X-Outpost-Signature' header to webhook requests." required:"N"`
39
+
DisableDefaultTimestampHeaderbool`yaml:"disable_default_timestamp_header" env:"DESTINATIONS_WEBHOOK_DISABLE_DEFAULT_TIMESTAMP_HEADER" desc:"If true, disables adding the default 'X-Outpost-Timestamp' header to webhook requests." required:"N"`
40
+
DisableDefaultTopicHeaderbool`yaml:"disable_default_topic_header" env:"DESTINATIONS_WEBHOOK_DISABLE_DEFAULT_TOPIC_HEADER" desc:"If true, disables adding the default 'X-Outpost-Topic' header to webhook requests." required:"N"`
41
+
SignatureContentTemplatestring`yaml:"signature_content_template" env:"DESTINATIONS_WEBHOOK_SIGNATURE_CONTENT_TEMPLATE" desc:"Go template for constructing the content to be signed for webhook requests." required:"N"`
42
+
SignatureHeaderTemplatestring`yaml:"signature_header_template" env:"DESTINATIONS_WEBHOOK_SIGNATURE_HEADER_TEMPLATE" desc:"Go template for the value of the signature header." required:"N"`
43
+
SignatureEncodingstring`yaml:"signature_encoding" env:"DESTINATIONS_WEBHOOK_SIGNATURE_ENCODING" desc:"Encoding for the signature (e.g., 'hex', 'base64')." required:"N"`
44
+
SignatureAlgorithmstring`yaml:"signature_algorithm" env:"DESTINATIONS_WEBHOOK_SIGNATURE_ALGORITHM" desc:"Algorithm used for signing webhook requests (e.g., 'hmac-sha256')." required:"N"`
45
45
}
46
46
47
47
// toConfig converts WebhookConfig to the provider config - private since it's only used internally
MetadataInPayloadbool`yaml:"metadata_in_payload" env:"DESTINATIONS_AWS_KINESIS_METADATA_IN_PAYLOAD" desc:"If true, includes Outpost metadata (event ID, topic, etc.) within the Kinesis record payload. Defaults to true." required:"N"`
64
+
MetadataInPayloadbool`yaml:"metadata_in_payload" env:"DESTINATIONS_AWS_KINESIS_METADATA_IN_PAYLOAD" desc:"If true, includes Outpost metadata (event ID, topic, etc.) within the Kinesis record payload." required:"N"`
65
65
}
66
66
67
67
// toConfig converts AWSKinesisConfig to the provider config
0 commit comments