Skip to content
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .changeset/partition-setting.md
Original file line number Diff line number Diff line change
@@ -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`.
3 changes: 3 additions & 0 deletions mise.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
3 changes: 3 additions & 0 deletions pystreams/src/pystreams/attr/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
16 changes: 16 additions & 0 deletions pystreams/src/pystreams/cmd/flags_service.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

import click

from pystreams import partition


def service_options() -> Sequence[click.Option]:
return [
Expand All @@ -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,
Expand Down
3 changes: 3 additions & 0 deletions pystreams/src/pystreams/cmd/multi.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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()
Expand All @@ -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,
)
Expand Down
2 changes: 2 additions & 0 deletions pystreams/src/pystreams/deps/otel.py
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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,
}
Expand Down
15 changes: 15 additions & 0 deletions pystreams/src/pystreams/partition.py
Original file line number Diff line number Diff line change
@@ -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)
2 changes: 2 additions & 0 deletions pystreams/tests/test_multi.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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,
Expand Down
2 changes: 2 additions & 0 deletions pystreams/tests/test_otel.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
}
Expand Down Expand Up @@ -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]
Expand Down
71 changes: 71 additions & 0 deletions pystreams/tests/test_partition.py
Original file line number Diff line number Diff line change
@@ -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])
1 change: 1 addition & 0 deletions server/cmd/gram/admin.go
Original file line number Diff line number Diff line change
Expand Up @@ -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"),
})
Expand Down
86 changes: 86 additions & 0 deletions server/cmd/gram/flags_partition.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
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 anywhere.
func printsHelpOrVersion(args []string) bool {
if len(args) == 0 {
return true
}

switch args[0] {
case "help", "h", "version":
return true
}

return slices.ContainsFunc(args, func(arg string) bool {
return arg == "--help" || arg == "-h"
Comment thread
cubic-dev-ai[bot] marked this conversation as resolved.
Resolved
})
}

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
}
Loading
Loading