feat(plugin): add observability operations

plugin/api/api.go

@@ -1,8 +1,12 @@
 package api
 
 import (
+	"context"
+	"io"
 	"net"
+	"net/http"
 	"sync"
+	"time"
 )
 
 type (
@@ -67,6 +71,85 @@ type (
 		ExitWaitGroup() *sync.WaitGroup
 
 		Hook(hook string, handler any) error
+
+		EmitEvent(ctx context.Context, name string, fields map[string]string) error
+		ObserveMetric(ctx context.Context, name string, value float64, labels map[string]string) error
+		Logger() Logger
+		DataStore() DataStore
+		FileStore() FileStore
+		ExternalClient(name string) ExternalClient
+		RegisterBackgroundTask(task BackgroundTask) error
+	}
+
+	EventSchema struct {
+		Name   string   `json:"name"`
+		Fields []string `json:"fields,omitempty"`
+	}
+
+	CustomMetricSchema struct {
+		Name   string   `json:"name"`
+		Type   string   `json:"type,omitempty"`
+		Labels []string `json:"labels,omitempty"`
+	}
+
+	Logger interface {
+		Debug(ctx context.Context, message string, fields map[string]string)
+		Info(ctx context.Context, message string, fields map[string]string)
+		Warn(ctx context.Context, message string, fields map[string]string)
+		Error(ctx context.Context, message string, fields map[string]string)
+	}
+
+	DataRecord struct {
+		Key           string
+		Value         []byte
+		SchemaVersion int
+		DataClass     string
+		Exportable    bool
+		Retention     time.Duration
+	}
+
+	DataStore interface {
+		Put(ctx context.Context, record DataRecord) error
+		Get(ctx context.Context, key string) (DataRecord, error)
+		Delete(ctx context.Context, key string) error
+	}
+
+	FileStore interface {
+		ResourcePath(name string) (string, error)
+		Write(ctx context.Context, namespace, name string, data []byte, dataClass string, retention time.Duration) error
+		Read(ctx context.Context, namespace, name string, maxBytes int64) ([]byte, error)
+		Delete(ctx context.Context, namespace, name string) error
+	}
+
+	ExternalRequest struct {
+		Method  string
+		URL     string
+		Header  http.Header
+		Body    io.Reader
+		Timeout time.Duration
+	}
+
+	ExternalResponse struct {
+		StatusCode int
+		Header     http.Header
+		Body       []byte
+	}
+
+	ExternalClient interface {
+		DoHTTP(ctx context.Context, req ExternalRequest) (ExternalResponse, error)
+		DialTCP(ctx context.Context, address string, timeout time.Duration) (net.Conn, error)
+		HealthCheck(ctx context.Context) error
+	}
+
+	BackgroundTask struct {
+		ID         string
+		Name       string
+		Interval   time.Duration
+		RunOnStart bool
+		Jitter     time.Duration
+		Timeout    time.Duration
+		Manual     bool
+		Run        func(context.Context) error
 	}
 
 	AbstractPlugin struct{}

plugin/api/api_test.go

@@ -1,9 +1,11 @@
 package api
 
 import (
+	"context"
 	"net"
 	"sync"
 	"testing"
+	"time"
 )
 
 func TestAbstractPluginDefaults(t *testing.T) {
@@ -92,3 +94,67 @@ func (g *recordingGateway) Hook(hook string, handler any) error {
 	g.hooks[hook] = handler
 	return nil
 }
+
+func (g *recordingGateway) EmitEvent(context.Context, string, map[string]string) error {
+	return nil
+}
+
+func (g *recordingGateway) ObserveMetric(context.Context, string, float64, map[string]string) error {
+	return nil
+}
+
+func (g *recordingGateway) Logger() Logger {
+	return testLogger{}
+}
+
+func (g *recordingGateway) DataStore() DataStore {
+	return testDataStore{}
+}
+
+func (g *recordingGateway) FileStore() FileStore {
+	return testFileStore{}
+}
+
+func (g *recordingGateway) ExternalClient(string) ExternalClient {
+	return testExternalClient{}
+}
+
+func (g *recordingGateway) RegisterBackgroundTask(BackgroundTask) error {
+	return nil
+}
+
+type testLogger struct{}
+
+func (testLogger) Debug(context.Context, string, map[string]string) {}
+func (testLogger) Info(context.Context, string, map[string]string)  {}
+func (testLogger) Warn(context.Context, string, map[string]string)  {}
+func (testLogger) Error(context.Context, string, map[string]string) {}
+
+type testDataStore struct{}
+
+func (testDataStore) Put(context.Context, DataRecord) error { return nil }
+func (testDataStore) Get(context.Context, string) (DataRecord, error) {
+	return DataRecord{}, nil
+}
+func (testDataStore) Delete(context.Context, string) error { return nil }
+
+type testFileStore struct{}
+
+func (testFileStore) ResourcePath(string) (string, error) { return "", nil }
+func (testFileStore) Write(context.Context, string, string, []byte, string, time.Duration) error {
+	return nil
+}
+func (testFileStore) Read(context.Context, string, string, int64) ([]byte, error) {
+	return nil, nil
+}
+func (testFileStore) Delete(context.Context, string, string) error { return nil }
+
+type testExternalClient struct{}
+
+func (testExternalClient) DoHTTP(context.Context, ExternalRequest) (ExternalResponse, error) {
+	return ExternalResponse{}, nil
+}
+func (testExternalClient) DialTCP(context.Context, string, time.Duration) (net.Conn, error) {
+	return nil, nil
+}
+func (testExternalClient) HealthCheck(context.Context) error { return nil }

plugin/api/hook.go

@@ -14,6 +14,9 @@ var (
 )
 
 type (
+	ConnectionIDContextKey struct{}
+	TraceIDContextKey      struct{}
+
 	HookType[Accept, Handler any] struct {
 		key string
 	}