cmd/mito: add package godoc

cmd/mito/main.go

@@ -15,14 +15,46 @@
 // specific language governing permissions and limitations
 // under the License.
 
+// The mito executable is a CEL program evaluation tool that allows development
+// of Filebeat CEL input integrations without the need to run have a running
+// stack. Not all feature of the Filebeat input are present, but most behaviors
+// that are needed to mimic an integration are available.
+//
+//	Usage of mito:
+//
+//	  mito [opts] <src.cel>
+//
+//	  -cfg string
+//	    	path to a YAML file holding run control configuration
+//	  -data string
+//	    	path to a JSON object holding input (exposed as the label state)
+//	  -insecure
+//	    	disable TLS verification in the HTTP client
+//	  -log_requests
+//	    	log request traces to stderr (go1.21+)
+//	  -max_executions int
+//	    	maximum number of evaluations, or no maximum if -1 (default -1)
+//	  -max_log_body int
+//	    	maximum length of body logged in request traces (go1.21+) (default 1000)
+//	  -use string
+//	    	libraries to use (default "all")
+//	  -version
+//	    	print version and exit
+//
+// The configuration accepted by mito in the configuration file is described by
+// the Go types in the [rc] package, [rc.Config], [rc.AuthConfig] and [rc.OAuth2Config].
 package main
 
 import (
 	"os"
 
 	"github.com/elastic/mito"
+	"github.com/elastic/mito/internal/rc"
 )
 
+// Used to allow documentation links to render.
+var _ rc.Config
+
 func main() {
 	os.Exit(mito.Main())
 }

internal/rc/rc.go

@@ -0,0 +1,72 @@
+// Licensed to Elasticsearch B.V. under one or more contributor
+// license agreements. See the NOTICE file distributed with
+// this work for additional information regarding copyright
+// ownership. Elasticsearch B.V. licenses this file to you under
+// the Apache License, Version 2.0 (the "License"); you may
+// not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+// Package rc provides run control types for the mito tool and tests.
+package rc
+
+import (
+	"net/url"
+
+	"github.com/elastic/mito/lib"
+)
+
+// Config controls configuration of the mito tool run behavior.
+type Config struct {
+	// Globals is the set of global variables available to the CEL environment.
+	Globals map[string]interface{} `yaml:"globals"`
+	// Regexps is a look-up into a table of pre-compiled regular expressions.
+	Regexps map[string]string `yaml:"regexp"`
+	// XSDs is a look-up into a table of pre-compiled XML document descriptions.
+	XSDs map[string]string `yaml:"xsd"`
+	// Auth is the authentication configuration for HTTP requests.
+	Auth *AuthConfig `yaml:"auth"`
+	// MaxExecutions is the maximum number of want_more executions for a single
+	// run of mito. This value is overridden by the -max_executions command
+	// line flag.
+	MaxExecutions *int `yaml:"max_executions"`
+}
+
+// AuthConfig controls configuration of HTTP request authentication behavior.
+type AuthConfig struct {
+	// Basic is a Basic Authentication configuration.
+	Basic *lib.BasicAuth `yaml:"basic"`
+	// OAuth2 is an OAuth2.0 authentication configuration.
+	OAuth2 *OAuth2Config `yaml:"oauth2"`
+}
+
+// OAuth2Config controls configuration of HTTP OAuth2.0 request authentication
+// behavior.
+type OAuth2Config struct {
+	Provider string `yaml:"provider"`
+
+	ClientID       string     `yaml:"client.id"`
+	ClientSecret   *string    `yaml:"client.secret"`
+	EndpointParams url.Values `yaml:"endpoint_params"`
+	Password       string     `yaml:"password"`
+	Scopes         []string   `yaml:"scopes"`
+	TokenURL       string     `yaml:"token_url"`
+	User           string     `yaml:"user"`
+
+	GoogleCredentialsFile  string `yaml:"google.credentials_file"`
+	GoogleCredentialsJSON  string `yaml:"google.credentials_json"`
+	GoogleJWTFile          string `yaml:"google.jwt_file"`
+	GoogleJWTJSON          string `yaml:"google.jwt_json"`
+	GoogleDelegatedAccount string `yaml:"google.delegated_account"`
+
+	AzureTenantID string `yaml:"azure.tenant_id"`
+	AzureResource string `yaml:"azure.resource"`
+}

mito.go

@@ -18,8 +18,7 @@
 // Package mito provides the logic for a main function and test infrastructure
 // for a CEL-based message stream processor.
 //
-// This repository is a design sketch. The majority of the logic resides in the
-// the lib package.
+// The majority of the logic resides in the the lib package.
 package mito
 
 import (
@@ -52,6 +51,7 @@ import (
 	"google.golang.org/protobuf/types/known/structpb"
 
 	"github.com/elastic/mito/internal/httplog"
+	"github.com/elastic/mito/internal/rc"
 	"github.com/elastic/mito/lib"
 )
 
@@ -69,7 +69,7 @@ func Main() int {
 	use := flag.String("use", "all", "libraries to use")
 	data := flag.String("data", "", "path to a JSON object holding input (exposed as the label "+root+")")
 	maxExecutions := flag.Int("max_executions", -1, "maximum number of evaluations, or no maximum if -1")
-	cfgPath := flag.String("cfg", "", "path to a YAML file holding configuration for global vars and regular expressions")
+	cfgPath := flag.String("cfg", "", "path to a YAML file holding run control configuration (see pkg.go.dev/github.com/elastic/mito/cmd/mito)")
 	insecure := flag.Bool("insecure", false, "disable TLS verification in the HTTP client")
 	logTrace := flag.Bool("log_requests", false, "log request traces to stderr (go1.21+)")
 	maxTraceBody := flag.Int("max_log_body", 1000, "maximum length of body logged in request traces (go1.21+)")
@@ -97,7 +97,7 @@ func Main() int {
 		}
 		defer f.Close()
 		dec := yaml.NewDecoder(f)
-		var cfg config
+		var cfg Config
 		err = dec.Decode(&cfg)
 		if err != nil {
 			fmt.Fprintln(os.Stderr, err)
@@ -412,41 +412,13 @@ func toUpper(p []byte) {
 	}
 }
 
-type config struct {
-	Globals       map[string]interface{} `yaml:"globals"`
-	Regexps       map[string]string      `yaml:"regexp"`
-	XSDs          map[string]string      `yaml:"xsd"`
-	Auth          *authConfig            `yaml:"auth"`
-	MaxExecutions *int                   `yaml:"max_executions"`
-}
-
-type authConfig struct {
-	Basic  *lib.BasicAuth `yaml:"basic"`
-	OAuth2 *oAuth2        `yaml:"oauth2"`
-}
-
-type oAuth2 struct {
-	Provider string `yaml:"provider"`
-
-	ClientID       string     `yaml:"client.id"`
-	ClientSecret   *string    `yaml:"client.secret"`
-	EndpointParams url.Values `yaml:"endpoint_params"`
-	Password       string     `yaml:"password"`
-	Scopes         []string   `yaml:"scopes"`
-	TokenURL       string     `yaml:"token_url"`
-	User           string     `yaml:"user"`
-
-	GoogleCredentialsFile  string `yaml:"google.credentials_file"`
-	GoogleCredentialsJSON  string `yaml:"google.credentials_json"`
-	GoogleJWTFile          string `yaml:"google.jwt_file"`
-	GoogleJWTJSON          string `yaml:"google.jwt_json"`
-	GoogleDelegatedAccount string `yaml:"google.delegated_account"`
-
-	AzureTenantID string `yaml:"azure.tenant_id"`
-	AzureResource string `yaml:"azure.resource"`
-}
+type (
+	Config     = rc.Config
+	AuthConfig = rc.AuthConfig
+	OAuth2     = rc.OAuth2Config
+)
 
-func oAuth2Client(cfg oAuth2) (*http.Client, error) {
+func oAuth2Client(cfg OAuth2) (*http.Client, error) {
 	ctx := context.WithValue(context.Background(), oauth2.HTTPClient, &http.Client{})
 
 	switch prov := strings.ToLower(cfg.Provider); prov {