Skip to content
Merged
Show file tree
Hide file tree
Changes from all 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
35 changes: 35 additions & 0 deletions docs/developer_guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -281,3 +281,38 @@ Future use cases for `UPDATE RETURNING`, `REPLACE RETURNING` and `DELETE RETURNI
Provider aliases, session SET/UNSET and secret storage are described in
[Provider sessions and secrets](provider_sessions.md), including SQL examples, permissions and parser
release sequencing.

## Opt-in endpoint selectors

Omni owns endpoint resolution through `ServerInputResolver`: selector evaluation, precedence,
conflicts, transport defaults and required-input reporting. StackQL supplies SQL inputs, session
alias defaults and `os.LookupEnv`, then consumes Omni's resolved bindings.
SELECT and mutations, SHOW METHODS required-input reporting, and EXEC follow the same order:

1. Explicit SQL input, including an EXEC argument.
2. Session provider-alias parameter default.
3. Non-empty `x-stackQL-envVar` override.
4. The selector's environment choice.
5. The selector's declared default key.
6. Unresolved: retain the required input; execution fails without it.

Unknown selector values and invalid selector defaults are errors rather than fallback choices.
Environment choices are case-sensitive after whitespace trimming; resolved endpoint values lose
trailing slashes. An unresolved legacy environment annotation stays required. Resolved variables
do not appear in SHOW METHODS' RequiredParams. Conflicting method endpoint choices require an
explicit input instead of selecting one arbitrarily.

Query binding calls `omnisdk.BindServerInputs`; EXEC uses `NewMethodInputResolver`, and
SHOW METHODS uses `NewDocMethodInputResolver`. All three share the same resolution policy. `completedMethod` retains the same metadata for awaited mutations.
Session alias parameters do not implicitly change OAuth token endpoints: use the alias's explicit
`auth.token_url` for a per-tenant authority. Document OAuth variables use the same annotations in
`config.auth.variables`, resolved by Omni before its existing environment-template expansion.

The companion requires an Omni release containing this API. Release/tag Omni, then update StackQL's
pinned module version before normal CI; no repository module replacement is supplied. The temporary
workspace used to verify coordinated source changes is outside both repositories.

`stackql_endpoint_selectors.robot` checks default selection, environment/direct overrides, explicit
SQL and alias precedence, SHOW METHODS, EXEC, mutations, token endpoints and pre-request errors.
It reuses the existing isolated native/Docker and SQLite/Postgres test harness; its new fixtures do
not change existing provider files or Robot inputs.
2 changes: 1 addition & 1 deletion go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ require (
github.com/spf13/cobra v1.10.2
github.com/spf13/pflag v1.0.10
github.com/spf13/viper v1.10.1
github.com/stackql-labs/omnisdk v0.1.9-beta05
github.com/stackql-labs/omnisdk v0.1.10-alpha04
github.com/stackql/go-suffix-map v0.0.1-alpha02
github.com/stackql/psql-wire v0.1.2-beta02
github.com/stackql/stackql-parser v0.0.17-alpha05
Expand Down
4 changes: 2 additions & 2 deletions go.sum
Original file line number Diff line number Diff line change
Expand Up @@ -328,8 +328,8 @@ github.com/spf13/viper v1.10.1 h1:nuJZuYpG7gTj/XqiUwg8bA0cp1+M2mC3J4g5luUYBKk=
github.com/spf13/viper v1.10.1/go.mod h1:IGlFPqhNAPKRxohIzWpI5QEy4kuI7tcl5WvR+8qy1rU=
github.com/spiffe/go-spiffe/v2 v2.7.0 h1:uXe1MflJoHw58wAUvxVlcM7WpKtijWG7I1UidcGh6g4=
github.com/spiffe/go-spiffe/v2 v2.7.0/go.mod h1:47Q0Q9/AqGha8QLHp+kxpH4Wca7X7EnOtlIJy3mxZ3U=
github.com/stackql-labs/omnisdk v0.1.9-beta05 h1:JhBSZ9DEVT13X3NR3HWP8Dy0X05QavG8A1Dwjh4eeSs=
github.com/stackql-labs/omnisdk v0.1.9-beta05/go.mod h1:pwxphb3OMfEui7uCMmReoB+ABshSBl83dszn4Sf4vcg=
github.com/stackql-labs/omnisdk v0.1.10-alpha04 h1:wADTbRDAsRnk23+iIFm2gL12ajqz7P9H7XYQ4VsegWg=
github.com/stackql-labs/omnisdk v0.1.10-alpha04/go.mod h1:pwxphb3OMfEui7uCMmReoB+ABshSBl83dszn4Sf4vcg=
github.com/stackql/go-suffix-map v0.0.1-alpha02 h1:JI4aiq/OfHW4a/BiNqK31NbyaR94zlUOhGZof3G/OUo=
github.com/stackql/go-suffix-map v0.0.1-alpha02/go.mod h1:6BSMz4K/gIYfqdVRb7V8xL165wiPYyCjD9Kx7hLMd9Y=
github.com/stackql/psql-wire v0.1.2-beta02 h1:7DfliBpyyCaUHVJ1Jxk37q3zVwVLyh6+FCHeM0/gbAQ=
Expand Down
7 changes: 7 additions & 0 deletions internal/stackql/intrinsic/completion_schema.go
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,13 @@ func newCompletedMethod(
}
func (m *completedMethod) Columns() []string { return slices.Clone(m.columns) }
func (m *completedMethod) ColumnTypes() map[string]omnisdk.ColumnType { return maps.Clone(m.types) }
func (m *completedMethod) ServerVariableSpecs() map[string]omnisdk.ServerVariableSpec {
if metadata, ok := m.MethodSignature.(omnisdk.ServerVariableSpecs); ok {
return metadata.ServerVariableSpecs()
}
return nil
}

func (m *completedMethod) ServerEnvironmentBindings() map[string]string {
if metadata, ok := m.MethodSignature.(omnisdk.ServerEnvironmentBindings); ok {
return metadata.ServerEnvironmentBindings()
Expand Down
12 changes: 8 additions & 4 deletions internal/stackql/intrinsic/doc.go
Original file line number Diff line number Diff line change
Expand Up @@ -138,14 +138,18 @@ func docMethods(ctx queryContext, bundle, service, resource string) ([]relationM
}
out := make([]relationMethod, 0, len(methods))
for _, method := range methods {
required := unresolvedServerParams(method)
defaults := sessionParameterDefaults(ctx, UnstablePrefix+bundle+"."+service+"."+resource)
required, resolutionErr := unresolvedServerParams(method, defaults)
if resolutionErr != nil {
return nil, resolutionErr
}
if method.Name != "__view__" {
signature, describeErr := omnisdk.DescribeMethod(
registryRoot(ctx), providerAddress(ctx, UnstablePrefix+bundle+"."+service+"."+resource), method.Name, opts...)
if describeErr != nil {
return nil, describeErr
}
required = requiredMethodInputs(method, signature)
required = requiredMethodInputs(required, signature)
}
out = append(out, relationMethod{
requiredParams: required,
Expand Down Expand Up @@ -610,8 +614,8 @@ func configureReadHints(translated docQuery, args *omnisdk.Args) {
}
}

func requiredMethodInputs(method omnisdk.DocMethod, signature omnisdk.MethodSignature) []string {
required := unresolvedServerParams(method)
func requiredMethodInputs(required []string, signature omnisdk.MethodSignature) []string {
required = slices.Clone(required)
metadata, ok := signature.(omnisdk.RequestMetadata)
if !ok || metadata.RequestBodySchema() == nil {
return required
Expand Down
3 changes: 3 additions & 0 deletions internal/stackql/intrinsic/exec.go
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,9 @@ func execPlan(ctx queryContext, node *sqlparser.Exec) (omnisdk.Plan, omnisdk.Met
name := execInputName(signature, variable.ColIdent.GetRawVal())
params[name] = fmt.Sprint(textValue(value))
}
if err = bindExecServerInputs(ctx, address, signature, params); err != nil {
return nil, nil, err
}
body, err := execPayload(node.OptExecPayload, signature)
if err != nil {
return nil, nil, err
Expand Down
77 changes: 35 additions & 42 deletions internal/stackql/intrinsic/server_environment.go
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
package intrinsic

import (
"fmt"
"maps"
"os"
"slices"
Expand All @@ -10,35 +9,38 @@ import (
"github.com/stackql-labs/omnisdk/pkg/query"
)

// Environment resolution is host policy, limited to explicit document annotations.
// SQL parameters take precedence. The SDK receives ordinary explicit bindings.
func bindServerEnvironment(q query.Unresolved, tables map[string]omnisdk.Table) (query.Unresolved, error) {
where := slices.Clone(q.Where())
for _, alias := range slices.Sorted(maps.Keys(tables)) {
declared := map[string]string{}
for _, method := range tables[alias].Methods() {
if metadata, ok := method.(omnisdk.ServerEnvironmentBindings); ok {
for name, environment := range metadata.ServerEnvironmentBindings() {
declared[name] = environment
}
}
}
for _, name := range slices.Sorted(maps.Keys(declared)) {
if explicitServerBinding(q, alias, name) {
continue
}
value, exists := os.LookupEnv(declared[name])
if !exists || value == "" {
return nil, fmt.Errorf("cannot find any viable servers: %s requires %s", alias, name)
}
where = append(where, query.NewEq(query.NewColumn(alias, name), query.NewLiteral(value)))
}
return omnisdk.BindServerInputs(q, tables, os.LookupEnv)
}

func unresolvedServerParams(method omnisdk.DocMethod, defaults map[string]string) ([]string, error) {
return omnisdk.NewDocMethodInputResolver(method, defaults, os.LookupEnv).Required(method.RequiredParams, nil)
}

func sessionParameterDefaults(ctx queryContext, address string) map[string]string {
if host, ok := ctx.(interface {
ProviderBindingParams(string) map[string]string
}); ok {
return host.ProviderBindingParams(address)
}
bound, err := queryWithWhere(q, where)
return nil
}

func bindExecServerInputs(
ctx queryContext, address string, signature omnisdk.MethodSignature, params map[string]string,
) error {
resolver := omnisdk.NewMethodInputResolver(
[]omnisdk.MethodSignature{signature}, sessionParameterDefaults(ctx, address), os.LookupEnv,
)
bindings, err := resolver.Resolve(func(name string) bool {
_, exists := params[name]
return exists
})
if err != nil {
return nil, err
return err
}
return bindServerTransport(bound, tables)
maps.Copy(params, bindings)
return nil
}

func explicitServerBinding(q query.Unresolved, alias, name string) bool {
Expand Down Expand Up @@ -69,22 +71,6 @@ func explicitServerBinding(q query.Unresolved, alias, name string) bool {
return slices.ContainsFunc(target.Set(), func(assignment query.Assignment) bool { return assignment.Column() == name })
}

func unresolvedServerParams(method omnisdk.DocMethod) []string {
required := make([]string, 0, len(method.RequiredParams))
for _, name := range method.RequiredParams {
if method.TransportDefaults[name] != "" {
continue
}
if environment := method.ServerEnvironment[name]; environment != "" {
if value, exists := os.LookupEnv(environment); exists && value != "" {
continue
}
}
required = append(required, name)
}
return required
}

// bindReadPageSize retains the CLI's request size independently of a SQL LIMIT.
// Only declared query parameters are supplied, and explicit SQL bindings win.
func bindReadPageSize(q query.Unresolved, tables map[string]omnisdk.Table, size int) (query.Unresolved, error) {
Expand All @@ -108,3 +94,10 @@ func bindReadPageSize(q query.Unresolved, tables map[string]omnisdk.Table, size
}
return queryWithWhere(q, where)
}

func queryWithWhere(q query.Unresolved, where []query.Predicate) (query.Unresolved, error) {
if target := q.Target(); target != nil {
return query.NewMutation(target, q.From(), where, q.Select())
}
return query.New(q.From(), where, q.Select())
}
13 changes: 11 additions & 2 deletions internal/stackql/intrinsic/server_environment_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ components:
t.Fatalf("binding=%v want=%v", got, expected)
}
}
if got := unresolvedServerParams(methods[0]); len(got) != 0 {
if got := serverRequiredParams(t, methods[0]); len(got) != 0 {
t.Fatalf("env-resolved required=%v", got)
}
t.Setenv("OMNI_EXPLICIT_TEST_DEPLOYMENT", "")
Expand All @@ -86,7 +86,16 @@ components:
if _, err := bindServerEnvironment(original, tables); err == nil {
t.Fatal("missing environment silently used document default")
}
if got := unresolvedServerParams(methods[0]); len(got) != 1 || got[0] != "deployment" {
if got := serverRequiredParams(t, methods[0]); len(got) != 1 || got[0] != "deployment" {
t.Fatalf("unresolved required=%v", got)
}
}

func serverRequiredParams(t *testing.T, method omnisdk.DocMethod) []string {
t.Helper()
required, err := unresolvedServerParams(method, nil)
if err != nil {
t.Fatal(err)
}
return required
}
52 changes: 0 additions & 52 deletions internal/stackql/intrinsic/server_transport.go

This file was deleted.

2 changes: 1 addition & 1 deletion internal/stackql/intrinsic/server_transport_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,7 @@ components:
if err != nil {
t.Fatal(err)
}
if got := unresolvedServerParams(methods[0]); !reflect.DeepEqual(got, []string{"host", "region"}) {
if got := serverRequiredParams(t, methods[0]); !reflect.DeepEqual(got, []string{"host", "region"}) {
t.Fatalf("required=%v", got)
}
}
Loading
Loading