diff --git a/.changeset/partition-setting.md b/.changeset/partition-setting.md new file mode 100644 index 00000000000..3c2e1ebdf98 --- /dev/null +++ b/.changeset/partition-setting.md @@ -0,0 +1,6 @@ +--- +"server": minor +"tunnel": minor +--- + +The Speakeasy server binary (every command, including mcp, worker, streams and admin), pystreams and the tunnel gateway require a `GRAM_PARTITION` setting (`us` or `eu`) naming the partition they run in. There is no default: each refuses to start when it is missing, empty or unknown, so a deployment cannot silently run as the wrong partition. Each tags its logs with `gram.partition`; the server and pystreams also put it on their traces and metrics. `gram version` and help output work without it. Local development sets `GRAM_PARTITION=us` in `mise.toml`. diff --git a/mise.toml b/mise.toml index 37bcff22027..57a7d8a6397 100644 --- a/mise.toml +++ b/mise.toml @@ -136,6 +136,9 @@ GRAM_RISK_LLM_API_KEY = "" ############################################### ## The following variable can be one of: local, test, prod GRAM_ENVIRONMENT = "local" +## Partition the processes run in: us or eu. Required, with no default in the +## server, pystreams or tunnel gateway, so local development sets it here. +GRAM_PARTITION = "us" GRAM_HOST = "localhost" # Only needed for local development. In production, you should set GRAM_SERVER_URL and GRAM_SITE_URL directly. ## Public listener hosts accept IPv4 or bracketed IPv6 literals (e.g. [::1]). ## Empty uses wildcard public listeners; health/control listeners use loopback. diff --git a/pystreams/src/pystreams/attr/__init__.py b/pystreams/src/pystreams/attr/__init__.py index 401f38a25a2..3b09a38430f 100644 --- a/pystreams/src/pystreams/attr/__init__.py +++ b/pystreams/src/pystreams/attr/__init__.py @@ -12,6 +12,9 @@ DATADOG_GIT_REPOSITORY_URL: Final = "git.repository_url" COMPONENT: Final = "gram.component" +# The Speakeasy partition (an independent production deployment, such as us or +# eu) that emitted the telemetry. Mirrors attr.PartitionKey in the Go server. +PARTITION: Final = "gram.partition" ORGANIZATION_ID: Final = "gram.org.id" ORGANIZATION_SLUG: Final = "gram.org.slug" PROJECT_ID: Final = "gram.project.id" diff --git a/pystreams/src/pystreams/cmd/flags_service.py b/pystreams/src/pystreams/cmd/flags_service.py index c81ec05bdf2..3b8c63f818e 100644 --- a/pystreams/src/pystreams/cmd/flags_service.py +++ b/pystreams/src/pystreams/cmd/flags_service.py @@ -2,6 +2,8 @@ import click +from pystreams import partition + def service_options() -> Sequence[click.Option]: return [ @@ -17,6 +19,20 @@ def service_options() -> Sequence[click.Option]: envvar="GRAM_ENVIRONMENT", help="Set the environment.", ), + click.Option( + ["--partition"], + type=click.Choice(partition.PARTITIONS, case_sensitive=True), + # No default: a deployment that forgets the partition fails at + # startup instead of running as the wrong one. Click treats a set + # but empty GRAM_PARTITION as unset, so it fails the same way, + # matching the Go server. + required=True, + envvar="GRAM_PARTITION", + show_envvar=True, + help="Partition this deployment runs in. A partition is an " + "independent production deployment with its own data stores and " + "hosts.", + ), click.Option( ["--git-sha"], type=str, diff --git a/pystreams/src/pystreams/cmd/multi.py b/pystreams/src/pystreams/cmd/multi.py index 862409ec6d0..a51367861f7 100644 --- a/pystreams/src/pystreams/cmd/multi.py +++ b/pystreams/src/pystreams/cmd/multi.py @@ -87,6 +87,7 @@ async def multi( # Service options service_version: str | None, environment: str | None, + partition: str, git_sha: str | None, log_level: str, pretty_log: bool, @@ -121,6 +122,7 @@ async def multi( attr.SERVICE_NAME: "gram-pystreams", attr.SERVICE_VERSION: service_version, attr.SERVICE_ENVIRONMENT: environment, + attr.PARTITION: partition, }, ) logger: structlog.stdlib.BoundLogger = structlog.get_logger() @@ -144,6 +146,7 @@ async def multi( service_version=service_version, git_sha=git_sha, environment=environment, + partition=partition, enable_tracing=enable_tracing, enable_metrics=enable_metrics, ) diff --git a/pystreams/src/pystreams/deps/otel.py b/pystreams/src/pystreams/deps/otel.py index a29df5e4c2c..b8d72c6dada 100644 --- a/pystreams/src/pystreams/deps/otel.py +++ b/pystreams/src/pystreams/deps/otel.py @@ -83,6 +83,7 @@ class OTelOptions: service_version: str | None git_sha: str | None environment: str | None + partition: str enable_tracing: bool enable_metrics: bool @@ -186,6 +187,7 @@ def _build_resource(options: OTelOptions) -> Resource: attr.SERVICE_NAME: options.service_name, attr.SERVICE_VERSION: options.service_version, attr.SERVICE_ENVIRONMENT: options.environment, + attr.PARTITION: options.partition, attr.DATADOG_GIT_COMMIT_SHA: options.git_sha, attr.DATADOG_GIT_REPOSITORY_URL: _REPOSITORY_URL, } diff --git a/pystreams/src/pystreams/partition.py b/pystreams/src/pystreams/partition.py new file mode 100644 index 00000000000..dde334e739b --- /dev/null +++ b/pystreams/src/pystreams/partition.py @@ -0,0 +1,15 @@ +"""The Speakeasy partition a process runs in. + +A partition is an independent production deployment with its own data stores +and hosts. The set is closed and mirrors ``server/internal/partition`` in the Go +server: adding a partition is a code change in both, so a typo in configuration +fails at startup instead of silently naming a new partition. +""" + +from typing import Final + +US: Final = "us" +EU: Final = "eu" + +# Every known partition, in the same order as ``partition.All`` in Go. +PARTITIONS: Final = (US, EU) diff --git a/pystreams/tests/test_multi.py b/pystreams/tests/test_multi.py index 88b8fb67ae9..186b10bd6a0 100644 --- a/pystreams/tests/test_multi.py +++ b/pystreams/tests/test_multi.py @@ -56,6 +56,7 @@ def fake_activate(*_args, **_kwargs): await multi_mod.multi( service_version=None, environment="local", + partition="us", git_sha=None, log_level="INFO", pretty_log=False, @@ -155,6 +156,7 @@ async def test_enforcement_role_requires_redis_and_pepper( await multi_mod.multi( service_version=None, environment="local", + partition="us", git_sha=None, log_level="INFO", pretty_log=False, diff --git a/pystreams/tests/test_otel.py b/pystreams/tests/test_otel.py index 99259b3327f..f0e69fc6004 100644 --- a/pystreams/tests/test_otel.py +++ b/pystreams/tests/test_otel.py @@ -21,6 +21,7 @@ def _options(**overrides) -> otel.OTelOptions: "service_version": "1.2.3", "git_sha": "abc123", "environment": "test", + "partition": "eu", "enable_tracing": False, "enable_metrics": False, } @@ -50,6 +51,7 @@ def test_build_resource_includes_git_and_service_attrs(): assert resource.attributes[attr.SERVICE_NAME] == "gram-pystreams" assert resource.attributes[attr.SERVICE_VERSION] == "1.2.3" assert resource.attributes[attr.SERVICE_ENVIRONMENT] == "test" + assert resource.attributes[attr.PARTITION] == "eu" assert resource.attributes[attr.DATADOG_GIT_COMMIT_SHA] == "abc123" assert ( resource.attributes[attr.DATADOG_GIT_REPOSITORY_URL] diff --git a/pystreams/tests/test_partition.py b/pystreams/tests/test_partition.py new file mode 100644 index 00000000000..21476bf8d98 --- /dev/null +++ b/pystreams/tests/test_partition.py @@ -0,0 +1,71 @@ +"""The partition option and its closed set of values. + +The set mirrors ``server/internal/partition`` in the Go server. The golden +values below must change together with ``partition.All`` there, so the two +services never disagree about which partitions exist. +""" + +import click +import pytest +from click.testing import CliRunner + +from pystreams import partition +from pystreams.cmd.flags_service import service_options + + +@pytest.fixture +def parse(monkeypatch: pytest.MonkeyPatch): + """Parse argv/env through a command carrying only the service options. + + Clears any ambient GRAM_PARTITION so a value exported in the shell cannot + change the outcome; tests pass the environment they need explicitly. + """ + monkeypatch.delenv("GRAM_PARTITION", raising=False) + + def _parse(args: list[str], env: dict[str, str] | None = None) -> dict: + captured: dict = {} + + def _record(**kwargs) -> None: + captured.update(kwargs) + + command = click.Command( + "probe", params=list(service_options()), callback=_record + ) + CliRunner().invoke( + command, args, env=env, standalone_mode=False, catch_exceptions=False + ) + return captured + + return _parse + + +def test_partitions_match_go_server(): + # Golden values from server/internal/partition (partition.All). + assert partition.PARTITIONS == ("us", "eu") + + +def test_partition_is_required(parse): + with pytest.raises(click.MissingParameter, match="partition"): + parse([]) + + +def test_partition_reads_environment_variable(parse): + assert parse([], env={"GRAM_PARTITION": "eu"})["partition"] == "eu" + + +def test_empty_partition_environment_variable_is_rejected(parse): + # Matches the Go server, which rejects a set-but-empty GRAM_PARTITION. + with pytest.raises(click.MissingParameter, match="partition"): + parse([], env={"GRAM_PARTITION": ""}) + + +def test_explicit_partition_wins_over_empty_environment_variable(parse): + # Matches the Go server, where a --partition flag takes precedence over + # the environment variable. + assert parse(["--partition", "eu"], env={"GRAM_PARTITION": ""})["partition"] == "eu" + + +@pytest.mark.parametrize("bad", ["apac", "US", ""]) +def test_unknown_partition_is_rejected(parse, bad): + with pytest.raises(click.UsageError): + parse(["--partition", bad]) diff --git a/server/cmd/gram/admin.go b/server/cmd/gram/admin.go index 7eae921b6b6..f4eb52230a7 100644 --- a/server/cmd/gram/admin.go +++ b/server/cmd/gram/admin.go @@ -375,6 +375,7 @@ func newAdminCommand() *cli.Command { ServiceName: serviceName, ServiceVersion: shortGitSHA(), GitSHA: GitSHA, + Partition: PullPartition(ctx), EnableTracing: c.Bool("with-otel-tracing"), EnableMetrics: c.Bool("with-otel-metrics"), }) diff --git a/server/cmd/gram/flags_partition.go b/server/cmd/gram/flags_partition.go new file mode 100644 index 00000000000..9a846d16c46 --- /dev/null +++ b/server/cmd/gram/flags_partition.go @@ -0,0 +1,91 @@ +package gram + +import ( + "context" + "fmt" + "slices" + "strings" + + "github.com/urfave/cli/v2" + + "github.com/speakeasy-api/gram/server/internal/partition" +) + +const partitionFlag = "partition" + +// partitionCLIFlag selects the partition every command of this binary runs +// in. It has no default: a deployment that forgets it fails at startup rather +// than running as the wrong partition. It is a global flag, so a command added +// later requires it and gets the partition on its logs without registering the +// flag; commands that set up OpenTelemetry still pass PullPartition to +// o11y.SetupOTelSDK, which rejects an empty partition. +func partitionCLIFlag() cli.Flag { + return &cli.StringFlag{ + Name: partitionFlag, + Usage: fmt.Sprintf("Partition this deployment runs in, one of: %s. Required. A partition is an independent production deployment with its own data stores and hosts. As a global flag it goes before the command name.", strings.Join(partition.Names(), ", ")), + EnvVars: []string{"GRAM_PARTITION"}, + } +} + +// partitionFromCLI parses the global partition flag. It returns an empty +// partition and no error only for invocations that print help or the version, +// which must work without deployment configuration. A GRAM_PARTITION that is +// set but empty is rejected. +func partitionFromCLI(c *cli.Context) (partition.Partition, error) { + if !c.IsSet(partitionFlag) { + if printsHelpOrVersion(c.Args().Slice()) { + return "", nil + } + return "", fmt.Errorf("--%s (GRAM_PARTITION) is required: set it to one of %s", partitionFlag, strings.Join(partition.Names(), ", ")) + } + + p, err := partition.Parse(c.String(partitionFlag)) + if err != nil { + return "", fmt.Errorf("invalid --%s: %w", partitionFlag, err) + } + + return p, nil +} + +// printsHelpOrVersion reports whether the arguments after the global flags +// only print help or the version: no command, the help or version command, or +// a help flag. Arguments after a "--" terminator are positional, never flags, +// so a --help there does not exempt a command from requiring a partition. +func printsHelpOrVersion(args []string) bool { + if len(args) == 0 { + return true + } + + switch args[0] { + case "help", "h", "version": + return true + } + + if end := slices.Index(args, "--"); end >= 0 { + args = args[:end] + } + + return slices.ContainsFunc(args, func(arg string) bool { + return arg == "--help" || arg == "-h" + }) +} + +type partitionKey struct{} + +// PushPartition records the partition the root command parsed, so commands +// read the validated value instead of parsing the flag again. +func PushPartition(ctx context.Context, p partition.Partition) context.Context { + return context.WithValue(ctx, partitionKey{}, p) +} + +// PullPartition returns the partition recorded by PushPartition. It panics +// when none was recorded, because the root command records one before any +// command other than help or version runs. +func PullPartition(ctx context.Context) partition.Partition { + p, ok := ctx.Value(partitionKey{}).(partition.Partition) + if !ok { + panic("PullPartition: partition not found in context") + } + + return p +} diff --git a/server/cmd/gram/flags_partition_test.go b/server/cmd/gram/flags_partition_test.go new file mode 100644 index 00000000000..28ba0b009e3 --- /dev/null +++ b/server/cmd/gram/flags_partition_test.go @@ -0,0 +1,179 @@ +package gram + +import ( + "fmt" + "os" + "testing" + + "github.com/stretchr/testify/require" + "github.com/urfave/cli/v2" + + "github.com/speakeasy-api/gram/server/internal/partition" +) + +// runPartitionApp runs a minimal app with the global partition flag and +// returns the partition the root command recorded in the context. +func runPartitionApp(t *testing.T, args ...string) (partition.Partition, error) { + t.Helper() + + var got partition.Partition + app := &cli.App{ + Name: "gram", + Flags: []cli.Flag{partitionCLIFlag()}, + Before: func(c *cli.Context) error { + p, err := partitionFromCLI(c) + if err != nil { + return err + } + c.Context = PushPartition(c.Context, p) + return nil + }, + Commands: []*cli.Command{{ + Name: "probe", + Action: func(c *cli.Context) error { + got = PullPartition(c.Context) + return nil + }, + }}, + } + + if err := app.RunContext(t.Context(), append([]string{"gram"}, args...)); err != nil { + return "", fmt.Errorf("run app: %w", err) + } + + return got, nil +} + +func TestPartitionFlag_RequiredWhenUnset(t *testing.T) { + // Unset rather than empty: a value from the shell or mise.toml must not + // change the outcome. t.Setenv restores the original when the test ends. + t.Setenv("GRAM_PARTITION", "") + require.NoError(t, os.Unsetenv("GRAM_PARTITION")) + + _, err := runPartitionApp(t, "probe") + require.ErrorContains(t, err, "--partition (GRAM_PARTITION) is required: set it to one of us, eu") +} + +func TestPartitionFlag_ReachesSubcommand(t *testing.T) { + // Unset rather than empty: a value from the shell or mise.toml must not + // change the outcome. t.Setenv restores the original when the test ends. + t.Setenv("GRAM_PARTITION", "") + require.NoError(t, os.Unsetenv("GRAM_PARTITION")) + + got, err := runPartitionApp(t, "--partition", "eu", "probe") + require.NoError(t, err) + require.Equal(t, partition.EU, got) +} + +func TestPartitionFlag_ReadsEnvironmentVariable(t *testing.T) { + t.Setenv("GRAM_PARTITION", "eu") + + got, err := runPartitionApp(t, "probe") + require.NoError(t, err) + require.Equal(t, partition.EU, got) +} + +func TestPartitionFlag_RejectsEmptyEnvironmentVariable(t *testing.T) { + t.Setenv("GRAM_PARTITION", "") + + _, err := runPartitionApp(t, "probe") + require.ErrorContains(t, err, `invalid --partition: unknown partition ""`) +} + +func TestPartitionFlag_RejectsUnknownPartition(t *testing.T) { + // Unset rather than empty: a value from the shell or mise.toml must not + // change the outcome. t.Setenv restores the original when the test ends. + t.Setenv("GRAM_PARTITION", "") + require.NoError(t, os.Unsetenv("GRAM_PARTITION")) + + _, err := runPartitionApp(t, "--partition", "apac", "probe") + require.ErrorContains(t, err, `invalid --partition: unknown partition "apac"`) +} + +func TestApp_RequiresPartitionBeforeAnyCommand(t *testing.T) { + // Unset rather than empty: a value from the shell or mise.toml must not + // change the outcome. t.Setenv restores the original when the test ends. + t.Setenv("GRAM_PARTITION", "") + require.NoError(t, os.Unsetenv("GRAM_PARTITION")) + + err := newApp().RunContext(t.Context(), []string{"gram", "start"}) + require.ErrorContains(t, err, "--partition (GRAM_PARTITION) is required") +} + +func TestApp_RequiresPartitionWithHelpFlagAfterTerminator(t *testing.T) { + // Unset rather than empty: a value from the shell or mise.toml must not + // change the outcome. t.Setenv restores the original when the test ends. + t.Setenv("GRAM_PARTITION", "") + require.NoError(t, os.Unsetenv("GRAM_PARTITION")) + + err := newApp().RunContext(t.Context(), []string{"gram", "start", "--", "--help"}) + require.ErrorContains(t, err, "--partition (GRAM_PARTITION) is required") +} + +func TestApp_RejectsUnknownPartitionBeforeAnyCommand(t *testing.T) { + // Unset rather than empty: a value from the shell or mise.toml must not + // change the outcome. t.Setenv restores the original when the test ends. + t.Setenv("GRAM_PARTITION", "") + require.NoError(t, os.Unsetenv("GRAM_PARTITION")) + + err := newApp().RunContext(t.Context(), []string{"gram", "--partition", "apac", "version"}) + require.ErrorContains(t, err, `invalid --partition: unknown partition "apac"`) +} + +func TestApp_HelpAndVersionRunWithoutPartition(t *testing.T) { + // Unset rather than empty: a value from the shell or mise.toml must not + // change the outcome. t.Setenv restores the original when the test ends. + t.Setenv("GRAM_PARTITION", "") + require.NoError(t, os.Unsetenv("GRAM_PARTITION")) + + tests := []struct { + name string + args []string + }{ + {name: "version", args: []string{"gram", "version"}}, + {name: "help command", args: []string{"gram", "help"}}, + {name: "root help flag", args: []string{"gram", "--help"}}, + {name: "command help flag", args: []string{"gram", "start", "--help"}}, + } + for _, tc := range tests { //nolint:paralleltest // subtests share the parent's environment and urfave's help command + t.Run(tc.name, func(t *testing.T) { + require.NoError(t, newApp().RunContext(t.Context(), tc.args)) + }) + } +} + +func TestPrintsHelpOrVersion(t *testing.T) { + t.Parallel() + + tests := []struct { + name string + args []string + want bool + }{ + {name: "no command", args: nil, want: true}, + {name: "version", args: []string{"version"}, want: true}, + {name: "help command", args: []string{"help", "start"}, want: true}, + {name: "help flag after command", args: []string{"start", "--help"}, want: true}, + {name: "short help flag", args: []string{"worker", "-h"}, want: true}, + {name: "help flag before terminator", args: []string{"start", "--help", "--", "x"}, want: true}, + {name: "help flag after terminator", args: []string{"start", "--", "--help"}, want: false}, + {name: "short help flag after terminator", args: []string{"demo-seed", "--", "-h"}, want: false}, + {name: "service command", args: []string{"start"}, want: false}, + {name: "service command with flags", args: []string{"worker", "--environment", "prod"}, want: false}, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + t.Parallel() + + require.Equal(t, tc.want, printsHelpOrVersion(tc.args)) + }) + } +} + +func TestPullPartition_PanicsWithoutRootCommand(t *testing.T) { + t.Parallel() + + require.PanicsWithValue(t, "PullPartition: partition not found in context", func() { + PullPartition(t.Context()) + }) +} diff --git a/server/cmd/gram/mcp.go b/server/cmd/gram/mcp.go index f0bf1ef4d63..94ae2615a38 100644 --- a/server/cmd/gram/mcp.go +++ b/server/cmd/gram/mcp.go @@ -149,6 +149,7 @@ func runMCPServer(c *cli.Context, shutdown *mcpServerShutdown) error { ServiceName: serviceName, ServiceVersion: shortGitSHA(), GitSHA: GitSHA, + Partition: PullPartition(ctx), EnableTracing: c.Bool("with-otel-tracing"), EnableMetrics: c.Bool("with-otel-metrics"), }) diff --git a/server/cmd/gram/netingress_attestor.go b/server/cmd/gram/netingress_attestor.go index be0279a4d15..a4f564d4b12 100644 --- a/server/cmd/gram/netingress_attestor.go +++ b/server/cmd/gram/netingress_attestor.go @@ -87,6 +87,7 @@ func newNetingressAttestorCommand() *cli.Command { ServiceName: serviceName, ServiceVersion: shortGitSHA(), GitSHA: GitSHA, + Partition: PullPartition(ctx), EnableTracing: c.Bool("with-otel-tracing"), EnableMetrics: c.Bool("with-otel-metrics"), }) diff --git a/server/cmd/gram/network_ingress_worker.go b/server/cmd/gram/network_ingress_worker.go index 191886327a2..2f5c8b1fa24 100644 --- a/server/cmd/gram/network_ingress_worker.go +++ b/server/cmd/gram/network_ingress_worker.go @@ -145,7 +145,7 @@ func newNetworkIngressWorkerCommand() *cli.Command { ctx, cancel := context.WithCancel(c.Context) defer cancel() shutdownOTel, err := o11y.SetupOTelSDK(ctx, logger, o11y.SetupOTelSDKOptions{ - ServiceName: serviceName, ServiceVersion: shortGitSHA(), GitSHA: GitSHA, + ServiceName: serviceName, ServiceVersion: shortGitSHA(), GitSHA: GitSHA, Partition: PullPartition(ctx), EnableTracing: c.Bool("with-otel-tracing"), EnableMetrics: c.Bool("with-otel-metrics"), }) if err != nil { diff --git a/server/cmd/gram/private_ingress.go b/server/cmd/gram/private_ingress.go index 21dcb32969f..48c50d2103f 100644 --- a/server/cmd/gram/private_ingress.go +++ b/server/cmd/gram/private_ingress.go @@ -83,7 +83,7 @@ func newNetworkIngressServerCommand() *cli.Command { o11y.PullAppInfo(ctx).Command = "network-ingress-server" slog.SetDefault(logger) shutdown, err := o11y.SetupOTelSDK(ctx, logger, o11y.SetupOTelSDKOptions{ - ServiceName: "gram-network-ingress-server", ServiceVersion: shortGitSHA(), GitSHA: GitSHA, + ServiceName: "gram-network-ingress-server", ServiceVersion: shortGitSHA(), GitSHA: GitSHA, Partition: PullPartition(ctx), EnableTracing: c.Bool("with-otel-tracing"), EnableMetrics: c.Bool("with-otel-metrics"), }) if err != nil { diff --git a/server/cmd/gram/root.go b/server/cmd/gram/root.go index e71763ccb27..222aea23016 100644 --- a/server/cmd/gram/root.go +++ b/server/cmd/gram/root.go @@ -37,6 +37,7 @@ func newApp() *cli.App { Usage: "Enable pretty logging", EnvVars: []string{"GRAM_LOG_PRETTY"}, }, + partitionCLIFlag(), }, Commands: []*cli.Command{ newStartCommand(), @@ -61,6 +62,11 @@ func newApp() *cli.App { newVersionCommand(), }, Before: func(c *cli.Context) error { + p, err := partitionFromCLI(c) + if err != nil { + return err + } + c.Context = o11y.PushAppInfo(c.Context, &o11y.AppInfo{ Name: "gram", Command: "", @@ -75,6 +81,12 @@ func newApp() *cli.App { attr.SlogDataDogGitCommitSHA(GitSHA), attr.SlogDataDogGitRepoURL("github.com/speakeasy-api/gram"), ) + // Help and version run without a partition; every other command + // has one and carries it on every log line. + if p != "" { + c.Context = PushPartition(c.Context, p) + logger = logger.With(attr.SlogPartition(p)) + } // Sets `GOMEMLIMIT` to 90% of cgroup's memory limit. // Cgroups are Linux-only. Keep all real Linux errors visible. diff --git a/server/cmd/gram/start.go b/server/cmd/gram/start.go index edf553adb57..ce244098786 100644 --- a/server/cmd/gram/start.go +++ b/server/cmd/gram/start.go @@ -778,6 +778,7 @@ func newStartCommand() *cli.Command { ServiceName: serviceName, ServiceVersion: shortGitSHA(), GitSHA: GitSHA, + Partition: PullPartition(ctx), EnableTracing: c.Bool("with-otel-tracing"), EnableMetrics: c.Bool("with-otel-metrics"), }) diff --git a/server/cmd/gram/streams.go b/server/cmd/gram/streams.go index 5cd598deb5e..0a080d0a67d 100644 --- a/server/cmd/gram/streams.go +++ b/server/cmd/gram/streams.go @@ -389,6 +389,7 @@ func newStreamsCommand() *cli.Command { ServiceName: serviceName, ServiceVersion: shortGitSHA(), GitSHA: GitSHA, + Partition: PullPartition(ctx), EnableTracing: c.Bool("with-otel-tracing"), EnableMetrics: c.Bool("with-otel-metrics"), }) diff --git a/server/cmd/gram/tailnet_gateway.go b/server/cmd/gram/tailnet_gateway.go index f4b13536ea3..9dd5b9fe9ef 100644 --- a/server/cmd/gram/tailnet_gateway.go +++ b/server/cmd/gram/tailnet_gateway.go @@ -178,7 +178,7 @@ func newTailnetGatewayCommand() *cli.Command { defer cancel() shutdownOTel, err := o11y.SetupOTelSDK(ctx, logger, o11y.SetupOTelSDKOptions{ - ServiceName: serviceName, ServiceVersion: shortGitSHA(), GitSHA: GitSHA, + ServiceName: serviceName, ServiceVersion: shortGitSHA(), GitSHA: GitSHA, Partition: PullPartition(ctx), EnableTracing: c.Bool("with-otel-tracing"), EnableMetrics: c.Bool("with-otel-metrics"), }) if err != nil { diff --git a/server/cmd/gram/worker.go b/server/cmd/gram/worker.go index a437bff5269..8c3fbaa5ca5 100644 --- a/server/cmd/gram/worker.go +++ b/server/cmd/gram/worker.go @@ -415,6 +415,7 @@ func newWorkerCommand() *cli.Command { ServiceName: serviceName, ServiceVersion: shortGitSHA(), GitSHA: GitSHA, + Partition: PullPartition(ctx), EnableTracing: c.Bool("with-otel-tracing"), EnableMetrics: c.Bool("with-otel-metrics"), }) diff --git a/server/internal/attr/conventions.go b/server/internal/attr/conventions.go index aad8a99f123..a3bdcb147a4 100644 --- a/server/internal/attr/conventions.go +++ b/server/internal/attr/conventions.go @@ -702,6 +702,10 @@ const ( // told apart without revealing the key. EncryptionKeyFingerprintKey = attribute.Key("gram.encryption.key_fingerprint") + // PartitionKey is the Speakeasy partition (an independent production + // deployment, such as us or eu) that emitted the telemetry. + PartitionKey = attribute.Key("gram.partition") + // OrgEncryptionUseCaseKey is the organization encryption use case a value // or key belongs to, such as oauth-session-tokens. OrgEncryptionUseCaseKey = attribute.Key("gram.orgencryption.use_case") @@ -2759,6 +2763,14 @@ func SlogEncryptionKeyFingerprint(v string) slog.Attr { return slog.String(string(EncryptionKeyFingerprintKey), v) } +func Partition[V ~string](v V) attribute.KeyValue { + return PartitionKey.String(string(v)) +} + +func SlogPartition[V ~string](v V) slog.Attr { + return slog.String(string(PartitionKey), string(v)) +} + func OrgEncryptionUseCase[V ~string](v V) attribute.KeyValue { return OrgEncryptionUseCaseKey.String(string(v)) } diff --git a/server/internal/o11y/setup.go b/server/internal/o11y/setup.go index 8e897737868..b28949ddc8e 100644 --- a/server/internal/o11y/setup.go +++ b/server/internal/o11y/setup.go @@ -24,19 +24,31 @@ import ( "goa.design/clue/clue" "github.com/speakeasy-api/gram/server/internal/attr" + "github.com/speakeasy-api/gram/server/internal/partition" ) type SetupOTelSDKOptions struct { ServiceName string ServiceVersion string GitSHA string - EnableTracing bool - EnableMetrics bool + + // Partition is the Speakeasy partition the process runs in. It is added + // to the resource so every span and metric carries it. SetupOTelSDK + // rejects a partition that partition.Parse does not accept, including + // the empty zero value. + Partition partition.Partition + + EnableTracing bool + EnableMetrics bool } // SetupOTelSDK bootstraps the OpenTelemetry pipeline. // If it does not return an error, make sure to call shutdown for proper cleanup. func SetupOTelSDK(ctx context.Context, logger *slog.Logger, options SetupOTelSDKOptions) (shutdown func(context.Context) error, err error) { + if _, err := partition.Parse(options.Partition.String()); err != nil { + return nil, fmt.Errorf("otel resource partition: %w", err) + } + logger = logger.With(attr.SlogComponent("otel")) var shutdownFuncs []func(context.Context) error @@ -114,6 +126,7 @@ func SetupOTelSDK(ctx context.Context, logger *slog.Logger, options SetupOTelSDK options.ServiceName, options.ServiceVersion, options.GitSHA, + options.Partition, metricExporter, spanExporter, prop, @@ -145,6 +158,7 @@ func newClueConfig( svcName string, svcVersion string, gitSHA string, + part partition.Partition, metricExporter sdkmetric.Exporter, spanExporter sdktrace.SpanExporter, propagators propagation.TextMapPropagator, @@ -159,6 +173,7 @@ func newClueConfig( semconv.ServiceVersionKey.String(svcVersion), attr.DataDogGitCommitSHA(gitSHA), attr.DataDogGitRepoURL("github.com/speakeasy-api/gram"), + attr.Partition(part), )) if err != nil { return nil, fmt.Errorf("create resource: %w", err) diff --git a/server/internal/o11y/setup_resource_test.go b/server/internal/o11y/setup_resource_test.go new file mode 100644 index 00000000000..f3d5ae51573 --- /dev/null +++ b/server/internal/o11y/setup_resource_test.go @@ -0,0 +1,49 @@ +package o11y + +import ( + "context" + "testing" + + "github.com/stretchr/testify/require" + "go.opentelemetry.io/otel" + "go.opentelemetry.io/otel/propagation" + sdktrace "go.opentelemetry.io/otel/sdk/trace" + "go.opentelemetry.io/otel/sdk/trace/tracetest" + + "github.com/speakeasy-api/gram/server/internal/attr" + "github.com/speakeasy-api/gram/server/internal/partition" +) + +func TestNewClueConfig_ResourceCarriesPartition(t *testing.T) { + t.Parallel() + + exporter := tracetest.NewInMemoryExporter() + cfg, err := newClueConfig( + t.Context(), + "gram-test", + "test", + "deadbeef", + partition.EU, + nil, + exporter, + propagation.TraceContext{}, + sdktrace.AlwaysSample(), + otel.ErrorHandlerFunc(func(err error) { require.NoError(t, err) }), + ) + require.NoError(t, err) + + provider, ok := cfg.TracerProvider.(*sdktrace.TracerProvider) + require.True(t, ok) + t.Cleanup(func() { require.NoError(t, provider.Shutdown(context.Background())) }) + + _, span := provider.Tracer("test").Start(t.Context(), "probe") + span.End() + require.NoError(t, provider.ForceFlush(t.Context())) + + spans := exporter.GetSpans() + require.Len(t, spans, 1) + + value, found := spans[0].Resource.Set().Value(attr.PartitionKey) + require.True(t, found) + require.Equal(t, "eu", value.AsString()) +} diff --git a/server/internal/o11y/setup_test.go b/server/internal/o11y/setup_test.go index 6386e8eb30d..95b1b6ad0c0 100644 --- a/server/internal/o11y/setup_test.go +++ b/server/internal/o11y/setup_test.go @@ -4,6 +4,7 @@ import ( "testing" "github.com/speakeasy-api/gram/server/internal/o11y" + "github.com/speakeasy-api/gram/server/internal/partition" "github.com/speakeasy-api/gram/server/internal/testenv" "github.com/stretchr/testify/require" ) @@ -15,6 +16,7 @@ func TestSetupOTelSDK(t *testing.T) { shutdown, err := o11y.SetupOTelSDK(t.Context(), logger, o11y.SetupOTelSDKOptions{ ServiceName: "gram-test", ServiceVersion: "0.1.0", + Partition: partition.US, EnableTracing: true, EnableMetrics: true, }) @@ -24,3 +26,16 @@ func TestSetupOTelSDK(t *testing.T) { err = shutdown(t.Context()) require.NoError(t, err) } + +func TestSetupOTelSDK_RejectsMissingPartition(t *testing.T) { + t.Parallel() + + shutdown, err := o11y.SetupOTelSDK(t.Context(), testenv.NewLogger(t), o11y.SetupOTelSDKOptions{ + ServiceName: "gram-test", + ServiceVersion: "0.1.0", + EnableTracing: false, + EnableMetrics: false, + }) + require.ErrorContains(t, err, `otel resource partition: unknown partition ""`) + require.Nil(t, shutdown) +} diff --git a/server/internal/partition/partition.go b/server/internal/partition/partition.go new file mode 100644 index 00000000000..0b6999b9708 --- /dev/null +++ b/server/internal/partition/partition.go @@ -0,0 +1,55 @@ +// Package partition identifies the Speakeasy partition a process runs in. A +// partition is an independent production deployment with its own data stores +// and hosts; nothing at runtime crosses between partitions. Organizations are +// assigned to exactly one partition. +package partition + +import ( + "fmt" + "slices" + "strings" +) + +// Partition names one partition. The set is closed: adding a partition is a +// code change, so a typo in configuration fails at startup instead of +// silently creating a new partition. +type Partition string + +const ( + // US is the original production deployment. Organizations without a + // recorded partition belong to it. + US Partition = "us" + + // EU is the deployment that keeps customer data in EU locations. + EU Partition = "eu" +) + +// All lists every known partition in a stable order. +func All() []Partition { + return []Partition{US, EU} +} + +// Parse returns the partition named by raw. Names are case sensitive and must +// be one of All. +func Parse(raw string) (Partition, error) { + p := Partition(raw) + if !slices.Contains(All(), p) { + return "", fmt.Errorf("unknown partition %q: must be one of %s", raw, strings.Join(Names(), ", ")) + } + + return p, nil +} + +func (p Partition) String() string { + return string(p) +} + +// Names lists the name of every known partition, in the order of All. +func Names() []string { + names := make([]string, 0, len(All())) + for _, p := range All() { + names = append(names, p.String()) + } + + return names +} diff --git a/server/internal/partition/partition_test.go b/server/internal/partition/partition_test.go new file mode 100644 index 00000000000..f88c7fc3031 --- /dev/null +++ b/server/internal/partition/partition_test.go @@ -0,0 +1,45 @@ +package partition_test + +import ( + "testing" + + "github.com/stretchr/testify/require" + + "github.com/speakeasy-api/gram/server/internal/partition" +) + +func TestParse_KnownPartitions(t *testing.T) { + t.Parallel() + + for _, want := range partition.All() { + t.Run(want.String(), func(t *testing.T) { + t.Parallel() + + got, err := partition.Parse(want.String()) + require.NoError(t, err) + require.Equal(t, want, got) + }) + } +} + +func TestParse_RejectsUnknownNames(t *testing.T) { + t.Parallel() + + tests := []struct { + name string + raw string + }{ + {name: "empty", raw: ""}, + {name: "unknown", raw: "apac"}, + {name: "uppercase", raw: "US"}, + {name: "padded", raw: " us"}, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + t.Parallel() + + _, err := partition.Parse(tc.raw) + require.ErrorContains(t, err, "must be one of us, eu") + }) + } +} diff --git a/tunnel/cmd/tunnel-gateway/main.go b/tunnel/cmd/tunnel-gateway/main.go index 49cccba2eb5..cabe8bf31e2 100644 --- a/tunnel/cmd/tunnel-gateway/main.go +++ b/tunnel/cmd/tunnel-gateway/main.go @@ -4,10 +4,12 @@ package main import ( "context" "errors" + "fmt" "log/slog" "net/http" "os" "os/signal" + "slices" "strconv" "strings" "sync" @@ -22,9 +24,25 @@ import ( "github.com/speakeasy-api/gram/tunnel/route" ) +// partitionAttrKey matches the gram.partition attribute the Speakeasy server +// puts on its logs, so the gateway's logs filter the same way. +const partitionAttrKey = "gram.partition" + +// knownPartitions mirrors the closed set in server/internal/partition. Go's +// internal visibility rule keeps this package from importing it, so the list +// is repeated here and the tests pin it. +var knownPartitions = []string{"us", "eu"} + func main() { logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelInfo})) + partition, err := parsePartition(os.Getenv("GRAM_PARTITION")) + if err != nil { + logger.ErrorContext(context.Background(), "invalid GRAM_PARTITION", slog.Any("error", err)) + os.Exit(2) + } + logger = logger.With(slog.String(partitionAttrKey, partition)) + publicListenAddr := envOr("TUNNEL_GATEWAY_PUBLIC_ADDR", envOr("TUNNEL_GATEWAY_ADDR", ":8090")) forwardListenAddr := envOr("TUNNEL_GATEWAY_FORWARD_ADDR", ":8091") // AdvertiseAddr is the internal gram-server -> gateway address, not the public agent URL. @@ -198,3 +216,16 @@ func parseMaxSessions(raw string) (int, error) { } return parsed, nil } + +// parsePartition returns the partition named by GRAM_PARTITION. It has no +// default: unset, empty or unknown is an error, as in the server, so a +// deployment that forgets it fails at startup. +func parsePartition(raw string) (string, error) { + if raw == "" { + return "", fmt.Errorf("GRAM_PARTITION is required: set it to one of %s", strings.Join(knownPartitions, ", ")) + } + if !slices.Contains(knownPartitions, raw) { + return "", fmt.Errorf("unknown partition %q: must be one of %s", raw, strings.Join(knownPartitions, ", ")) + } + return raw, nil +} diff --git a/tunnel/cmd/tunnel-gateway/main_test.go b/tunnel/cmd/tunnel-gateway/main_test.go index a1806351e4d..23a1c7f7d65 100644 --- a/tunnel/cmd/tunnel-gateway/main_test.go +++ b/tunnel/cmd/tunnel-gateway/main_test.go @@ -29,3 +29,28 @@ func TestParseMaxSessionsRejectsInvalidValue(t *testing.T) { _, err = parseMaxSessions("-1") require.Error(t, err) } + +func TestParsePartitionAcceptsKnownPartitions(t *testing.T) { + for _, want := range []string{"us", "eu"} { + got, err := parsePartition(want) + require.NoError(t, err) + require.Equal(t, want, got) + } +} + +func TestParsePartitionRejectsMissingOrUnknown(t *testing.T) { + tests := []struct { + name string + raw string + wantErr string + }{ + {name: "missing", raw: "", wantErr: "GRAM_PARTITION is required: set it to one of us, eu"}, + {name: "unknown", raw: "apac", wantErr: `unknown partition "apac"`}, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + _, err := parsePartition(tc.raw) + require.ErrorContains(t, err, tc.wantErr) + }) + } +}