Merge branch 'main' into sync_by_region

Author: joel-rieke

ReadMe.md

@@ -9,24 +9,37 @@
 [![PkgGoDev](https://img.shields.io/badge/go.dev-docs-007d9c?logo=go&logoColor=white&style=flat-square)](https://pkg.go.dev/github.com/trimble-oss/tierceron-core)
 
 ## What is it?
-Tierceron-core is an interface definition project in support of the tierceron hive.  It provides a list of supported events emitted by the hive kernel.
+Tierceron-core is the shared Go module for Tierceron runtime, transport, and flow plumbing. It packages the reusable APIs, plugin coordination types, filesystem abstractions, statistics protobufs, and utility layers that higher-level Tierceron services import.
 
-## Why❓
-Tierceron hive utilizes trcsh to run as a service that
-delivers secrets securely to running [go plugin](https://pkg.go.dev/plugin) implementation of microservices.
+## What is in this repo?
+- `api`: REST, gRPC, and SOAP client support, endpoint definitions, TLS configuration, retry handling, and example code.
+- `core`: plugin event types, chat and command channels, configuration context, data-flow statistics, plugin synchronization, and core configuration helpers.
+- `flow`: the flow processing framework for initializing and running Tierceron data pipelines.
+- `statsdk`: generated protobuf and gRPC definitions for statistics exchange.
+- `trcshfs`: shell-facing filesystem abstractions and `trcshio` helpers.
+- `bitlock`, `util`, and `util/mlock`: shared locking and utility helpers.
+- `atrium`, `buildopts`, `prod`, and `shell`: build options and runtime support packages used by dependent Tierceron components.
 
 ## Key Features
-* Configurations delivered in memory from vault to trcsh kernel directly to running tierceron plugin services via an 
-* Kernel services can be remotely managed via trcsh scripts running in a release pipeline.  These scripts require authentication in order to run
+- Multi-protocol API caller support for REST, gRPC, and SOAP integrations.
+- Shared kernel types for plugin lifecycle, chat exchange, command routing, and data-flow statistics.
+- Flow orchestration primitives for building reusable processing pipelines.
+- Shared protobuf and filesystem packages used across Tierceron services.
 
 
 ## Getting started
-If you are a contributor, please have a look on the [getting started](GETTING_STARTED.MD) file. Here you can check the information required and other things before providing a useful contribution.
+To work on the module locally:
+
+- Run `go test ./...` from the repository root.
+- See [api/README.md](api/README.md) for the standalone API caller package documentation.
+- See [api/TLS_USAGE.md](api/TLS_USAGE.md) for certificate and TLS configuration details.
+- Contributors should start with [GETTING_STARTED.MD](GETTING_STARTED.MD).
 
 ## Trusted Committers
 - [Joel Rieke](mailto:joel_rieke@trimble.com)
 - [David Mkrtychyan](mailto:david_mkrtychyan@trimble.com)
 - [Karnveer Gill](mailto:karnveer_gill@trimble.com)
+- [Meghan Bailey](mailto:meghan_bailey@trimble.com)
 
 ## Contributing
 Contributions are always welcome, no matter how large or small. Before contributing, please read the [code of conduct](CODE_OF_CONDUCT.MD).
@@ -36,5 +49,5 @@ See [Contributing](CONTRIBUTING.MD).
 ## Code review
 Check the [code review](CODE_REVIEW.MD) information to find out how a **Pull Request** is evaluated for this project and what other coding standards you should consider when you want to contribute.
 
-## Current effort
-Titrating.  Tierceron can do a lot of things.  Some features are very easy to set up and use, others not so much.  Contributions welcomed!
+## Security
+Please review [SECURITY.md](SECURITY.md) for vulnerability reporting guidance.

SECURITY.md

@@ -2,9 +2,9 @@
 
 ## Reporting a Vulnerability
 
-Report security vulnerabilities by emailing the Trimble Cybersecurity team at:
+Report security vulnerabilities to the Trimble Cybersecurity team at:
 
-    cybersecurity@trimble.com
+<https://www.trimble.com/en/our-commitment/responsible-business/data-privacy-and-security/report-cybersecurity-issues/form>
 
 Report security vulnerabilities in third-party modules to the person or team maintaining the module.
 

api/api.go

@@ -159,14 +159,8 @@ func (e *Endpoint) Call(params map[string]any) (map[string]any, error) {
 	// Make the call with retry logic for timeouts
 	var response *Response
 	var callErr error
-	maxRetries := e.MaxRetries
-	if maxRetries < 0 {
-		maxRetries = 0
-	}
-	retryErrRange := e.RetryErrorRange
-	if retryErrRange < 0 {
-		retryErrRange = 0
-	}
+	maxRetries := max(e.MaxRetries, 0)
+	retryErrRange := max(e.RetryErrorRange, 0)
 
 	for attempt := 0; attempt <= maxRetries; attempt++ {
 		// Recreate context for each retry attempt

api/demo/main.go

@@ -76,7 +76,7 @@ func main() {
 		Timeout:      10 * time.Second,
 	}
 
-	params := map[string]interface{}{
+	params := map[string]any{
 		"method": "GET",
 		"headers": map[string]string{
 			"Accept":     "application/json",
@@ -101,12 +101,12 @@ func main() {
 		Timeout:      15 * time.Second,
 	}
 
-	postParams := map[string]interface{}{
+	postParams := map[string]any{
 		"method": "POST",
 		"headers": map[string]string{
 			"Content-Type": "application/json",
 		},
-		"body": map[string]interface{}{
+		"body": map[string]any{
 			"name":    "John Doe",
 			"email":   "john@example.com",
 			"message": "Hello from API caller!",
@@ -118,7 +118,7 @@ func main() {
 		log.Printf("REST POST Error: %v\n", err)
 	} else {
 		fmt.Printf("Status: %d\n", postResult["statusCode"])
-		if body, ok := postResult["body"].(map[string]interface{}); ok {
+		if body, ok := postResult["body"].(map[string]any); ok {
 			if json, ok := body["json"]; ok {
 				fmt.Printf("Echoed JSON: %v\n", json)
 			}
@@ -170,31 +170,31 @@ func main() {
 		wsdl   string
 		method string
 		action string
-		params map[string]interface{}
+		params map[string]any
 	}{
 		{
 			name:   "W3Schools Temperature Converter",
 			url:    "https://www.w3schools.com/xml/tempconvert.asmx",
 			wsdl:   "https://www.w3schools.com/xml/tempconvert.asmx?WSDL",
 			method: "CelsiusToFahrenheit",
 			action: "https://www.w3schools.com/xml/CelsiusToFahrenheit",
-			params: map[string]interface{}{"Celsius": "100"},
+			params: map[string]any{"Celsius": "100"},
 		},
 		{
 			name:   "DNEOnline Calculator",
 			url:    "http://www.dneonline.com/calculator.asmx",
 			wsdl:   "http://www.dneonline.com/calculator.asmx?WSDL",
 			method: "Add",
 			action: "http://tempuri.org/Add",
-			params: map[string]interface{}{"intA": "25", "intB": "17"},
+			params: map[string]any{"intA": "25", "intB": "17"},
 		},
 		{
 			name:   "Thomas Bayer Blz Service",
 			url:    "http://www.thomas-bayer.com/axis2/services/BLZService",
 			wsdl:   "http://www.thomas-bayer.com/axis2/services/BLZService?wsdl",
 			method: "getBank",
 			action: "",
-			params: map[string]interface{}{"blz": "66050000"},
+			params: map[string]any{"blz": "66050000"},
 		},
 	}
 
@@ -210,7 +210,7 @@ func main() {
 			WSDLUrl:      soapTest.wsdl,
 		}
 
-		soapParams := map[string]interface{}{
+		soapParams := map[string]any{
 			"method":     soapTest.method,
 			"soapAction": soapTest.action,
 			"body":       soapTest.params,
@@ -223,7 +223,7 @@ func main() {
 				fmt.Printf("✓ SOAP call succeeded!\n")
 				fmt.Printf("Status: %d\n", statusCode)
 
-				if body, ok := soapResult["body"].(map[string]interface{}); ok {
+				if body, ok := soapResult["body"].(map[string]any); ok {
 					fmt.Printf("Parsed SOAP Response (key-value pairs):\n")
 					for key, value := range body {
 						fmt.Printf("  %s: %v\n", key, value)
@@ -260,8 +260,8 @@ func main() {
 	}
 
 	// Simple parameter map - automatically converted to protobuf
-	grpcParams := map[string]interface{}{
-		"body": map[string]interface{}{
+	grpcParams := map[string]any{
+		"body": map[string]any{
 			"user_id": "12345",
 		},
 	}
@@ -273,7 +273,7 @@ func main() {
 	} else {
 		fmt.Printf("Status: %d\n", grpcResult["statusCode"])
 		// Body is automatically parsed from protobuf to map!
-		if body, ok := grpcResult["body"].(map[string]interface{}); ok {
+		if body, ok := grpcResult["body"].(map[string]any); ok {
 			fmt.Printf("Parsed gRPC Response:\n")
 			for key, value := range body {
 				fmt.Printf("  %s: %v\n", key, value)
@@ -292,7 +292,7 @@ func main() {
 		MaxRetries:   2,               // Retry up to 2 times on timeout
 	}
 
-	retryParams := map[string]interface{}{
+	retryParams := map[string]any{
 		"method": "GET",
 		"headers": map[string]string{
 			"Accept": "application/json",
@@ -363,43 +363,43 @@ func registerTestService(server *grpc.Server) error {
 	// Create a simple service descriptor programmatically
 	// This creates a UserService with a GetUser method
 	fileDesc := &descriptorpb.FileDescriptorProto{
-		Name:    proto.String("user.proto"),
-		Package: proto.String("user"),
+		Name:    new("user.proto"),
+		Package: new("user"),
 		MessageType: []*descriptorpb.DescriptorProto{
 			{
-				Name: proto.String("GetUserRequest"),
+				Name: new("GetUserRequest"),
 				Field: []*descriptorpb.FieldDescriptorProto{
 					{
-						Name:   proto.String("user_id"),
+						Name:   new("user_id"),
 						Number: proto.Int32(1),
 						Type:   descriptorpb.FieldDescriptorProto_TYPE_STRING.Enum(),
 						Label:  descriptorpb.FieldDescriptorProto_LABEL_OPTIONAL.Enum(),
 					},
 				},
 			},
 			{
-				Name: proto.String("GetUserResponse"),
+				Name: new("GetUserResponse"),
 				Field: []*descriptorpb.FieldDescriptorProto{
 					{
-						Name:   proto.String("user_id"),
+						Name:   new("user_id"),
 						Number: proto.Int32(1),
 						Type:   descriptorpb.FieldDescriptorProto_TYPE_STRING.Enum(),
 						Label:  descriptorpb.FieldDescriptorProto_LABEL_OPTIONAL.Enum(),
 					},
 					{
-						Name:   proto.String("name"),
+						Name:   new("name"),
 						Number: proto.Int32(2),
 						Type:   descriptorpb.FieldDescriptorProto_TYPE_STRING.Enum(),
 						Label:  descriptorpb.FieldDescriptorProto_LABEL_OPTIONAL.Enum(),
 					},
 					{
-						Name:   proto.String("email"),
+						Name:   new("email"),
 						Number: proto.Int32(3),
 						Type:   descriptorpb.FieldDescriptorProto_TYPE_STRING.Enum(),
 						Label:  descriptorpb.FieldDescriptorProto_LABEL_OPTIONAL.Enum(),
 					},
 					{
-						Name:   proto.String("message"),
+						Name:   new("message"),
 						Number: proto.Int32(4),
 						Type:   descriptorpb.FieldDescriptorProto_TYPE_STRING.Enum(),
 						Label:  descriptorpb.FieldDescriptorProto_LABEL_OPTIONAL.Enum(),
@@ -409,12 +409,12 @@ func registerTestService(server *grpc.Server) error {
 		},
 		Service: []*descriptorpb.ServiceDescriptorProto{
 			{
-				Name: proto.String("UserService"),
+				Name: new("UserService"),
 				Method: []*descriptorpb.MethodDescriptorProto{
 					{
-						Name:       proto.String("GetUser"),
-						InputType:  proto.String(".user.GetUserRequest"),
-						OutputType: proto.String(".user.GetUserResponse"),
+						Name:       new("GetUser"),
+						InputType:  new(".user.GetUserRequest"),
+						OutputType: new(".user.GetUserResponse"),
 					},
 				},
 			},
@@ -449,7 +449,7 @@ func registerTestService(server *grpc.Server) error {
 	methodDesc := methods.Get(0)
 
 	// Create a handler for the method
-	handler := func(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	handler := func(srv any, ctx context.Context, dec func(any) error, interceptor grpc.UnaryServerInterceptor) (any, error) {
 		// Create a dynamic request message
 		reqMsg := dynamicpb.NewMessage(methodDesc.Input())
 		if err := dec(reqMsg); err != nil {
@@ -479,7 +479,7 @@ func registerTestService(server *grpc.Server) error {
 	// Register the service and handler
 	serviceInfo := &grpc.ServiceDesc{
 		ServiceName: string(serviceDesc.FullName()),
-		HandlerType: (*interface{})(nil),
+		HandlerType: (*any)(nil),
 		Methods: []grpc.MethodDesc{
 			{
 				MethodName: string(methodDesc.Name()),

api/grpc_test.go

@@ -123,43 +123,43 @@ func startTestGRPCServer() (*grpc.Server, string, error) {
 func registerTestUserService(server *grpc.Server) error {
 	// Create service descriptor
 	fileDesc := &descriptorpb.FileDescriptorProto{
-		Name:    proto.String("user.proto"),
-		Package: proto.String("user"),
+		Name:    new("user.proto"),
+		Package: new("user"),
 		MessageType: []*descriptorpb.DescriptorProto{
 			{
-				Name: proto.String("GetUserRequest"),
+				Name: new("GetUserRequest"),
 				Field: []*descriptorpb.FieldDescriptorProto{
 					{
-						Name:   proto.String("user_id"),
+						Name:   new("user_id"),
 						Number: proto.Int32(1),
 						Type:   descriptorpb.FieldDescriptorProto_TYPE_STRING.Enum(),
 						Label:  descriptorpb.FieldDescriptorProto_LABEL_OPTIONAL.Enum(),
 					},
 				},
 			},
 			{
-				Name: proto.String("GetUserResponse"),
+				Name: new("GetUserResponse"),
 				Field: []*descriptorpb.FieldDescriptorProto{
 					{
-						Name:   proto.String("user_id"),
+						Name:   new("user_id"),
 						Number: proto.Int32(1),
 						Type:   descriptorpb.FieldDescriptorProto_TYPE_STRING.Enum(),
 						Label:  descriptorpb.FieldDescriptorProto_LABEL_OPTIONAL.Enum(),
 					},
 					{
-						Name:   proto.String("name"),
+						Name:   new("name"),
 						Number: proto.Int32(2),
 						Type:   descriptorpb.FieldDescriptorProto_TYPE_STRING.Enum(),
 						Label:  descriptorpb.FieldDescriptorProto_LABEL_OPTIONAL.Enum(),
 					},
 					{
-						Name:   proto.String("email"),
+						Name:   new("email"),
 						Number: proto.Int32(3),
 						Type:   descriptorpb.FieldDescriptorProto_TYPE_STRING.Enum(),
 						Label:  descriptorpb.FieldDescriptorProto_LABEL_OPTIONAL.Enum(),
 					},
 					{
-						Name:   proto.String("message"),
+						Name:   new("message"),
 						Number: proto.Int32(4),
 						Type:   descriptorpb.FieldDescriptorProto_TYPE_STRING.Enum(),
 						Label:  descriptorpb.FieldDescriptorProto_LABEL_OPTIONAL.Enum(),
@@ -169,12 +169,12 @@ func registerTestUserService(server *grpc.Server) error {
 		},
 		Service: []*descriptorpb.ServiceDescriptorProto{
 			{
-				Name: proto.String("UserService"),
+				Name: new("UserService"),
 				Method: []*descriptorpb.MethodDescriptorProto{
 					{
-						Name:       proto.String("GetUser"),
-						InputType:  proto.String(".user.GetUserRequest"),
-						OutputType: proto.String(".user.GetUserResponse"),
+						Name:       new("GetUser"),
+						InputType:  new(".user.GetUserRequest"),
+						OutputType: new(".user.GetUserResponse"),
 					},
 				},
 			},

api/rest_client.go

@@ -7,6 +7,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"io"
+	"maps"
 	"net/http"
 	"net/url"
 	"strings"
@@ -160,9 +161,7 @@ func encodeFormBody(body any) (io.Reader, error) {
 		return strings.NewReader(values.Encode()), nil
 	case map[string][]string:
 		values := url.Values{}
-		for key, value := range v {
-			values[key] = value
-		}
+		maps.Copy(values, v)
 		return strings.NewReader(values.Encode()), nil
 	case map[string]any:
 		values := url.Values{}