gatewayclient

README

Kwil Gateway(KGW) Go Client

This package provides a Go client for interacting with a Kwil Gateway(KGW).

The major feature this client provides compared to core/client is cookie-based authentication for data privacy concerned read requests. It'll automatically try to authenticate with the gateway if the gateway requires it.

This package is used by the kwil-cli to interact with the Kwil Gateway, mainly the kwil-cli database call subcommand. When you specify --authenticate flag, kwil-cli database call will use this gateway client to make the request.

Usage

Get familiar with core/client

Read the core/client README to get familiar with the basic functionalities of the client. The core/gatewayclient package is built on top of core/client, so you can use all the functionalities provided by core/client.

Create a Kwil Gateway Client

To use this client, you need to create a new client with the NewClient function from github.com/kwilteam/kwil-db/core/gatewayclient package.

clt, err := gatewayclient.NewClient(ctx, kgwProvider, &gatewayclient.GatewayOptions{
    Options: clientType.Options{
        Signer: &auth.EthPersonalSigner{Key: *pk},
    },
    AuthSignFunc: nil,
})

Options

GatewayOptions is a struct that embeds github.com/kwilteam/kwil-db/core/types/client.Options.

It also has two other optional fields:

• AuthSignFunc, allows you to provide a custom signing function for authentication, you can use it to do extra logic when the message is signed. If not provided, the client will use the default function which just call signer.Sign([]byte(message)).
• AuthCookieHandler, allows you to do extra logic when the cookie jar tries to save cookie.

An example using those options in kwil-cli:

• Options, see core/client for more details.
• AuthSignFunc, to prompt the user to sign the message
• AuthCookieHandler, to save the cookie to a file every time the client receives a cookie.

// cmd/kwil-cli/cmds/common/roundtripper.go L66

client, err := gatewayclient.NewClient(ctx, conf.Provider, &gatewayclient.GatewayOptions{
    Options: clientConfig,
    AuthSignFunc: func(message string, signer auth.Signer) (*auth.Signature, error) {
        assumeYes, err := GetAssumeYesFlag(cmd)
        if err != nil {
            return nil, err
        }

        if !assumeYes {
            err := promptMessage(message)
            if err != nil {
                return nil, err
            }
        }

        toSign := []byte(message)
        sig, err := signer.Sign(toSign)
        if err != nil {
            return nil, err
        }

        return sig, nil
    },
    AuthCookieHandler: func(c *http.Cookie) error {
        // persist the cookie
        return SaveCookie(KGWAuthTokenFilePath(), providerDomain, clientConfig.Signer.Identity(), c)
    },
})

Documentation

Overview

package gatewayclient implements a client for kwild that can also authenticate with a kwil gateway.

Index

• type GatewayAuthSignFunc
• type GatewayClient
  • func NewClient(ctx context.Context, target string, opts *GatewayOptions) (*GatewayClient, error)
  • func (c *GatewayClient) Authenticate(ctx context.Context) error
  • func (c *GatewayClient) Call(ctx context.Context, dbid string, action string, inputs []any) (*clientType.CallResult, error)
  • func (c *GatewayClient) CallAction(ctx context.Context, dbid string, action string, inputs []any) (*clientType.Records, error)
  • func (c *GatewayClient) GetAuthCookie() (cookie *http.Cookie, found bool)
  • func (c *GatewayClient) SetAuthCookie(cookie *http.Cookie) error
• type GatewayOptions
  • func DefaultOptions() *GatewayOptions
  • func (c *GatewayOptions) Apply(opt *GatewayOptions)

Types

type GatewayAuthSignFunc

type GatewayAuthSignFunc func(message string, signer auth.Signer) (*auth.Signature, error)

GatewayAuthSignFunc is the function that signs the authentication message.

type GatewayClient

type GatewayClient struct {
	client.Client // core client
	// contains filtered or unexported fields
}

GatewayClient is a client that is made to interact with a kwil gateway. It inherits the functionality of the main Kwil client, but also provides authentication cookies to the gateway. It automatically handles the authentication process with the gateway.

func NewClient

func NewClient(ctx context.Context, target string, opts *GatewayOptions) (*GatewayClient, error)

NewClient creates a new gateway client. The target should be the root URL of the gateway. It uses core/client as the underlying client to interact with the gateway for kwil-db specific jsonrpc requests, core/rpc/client/gateway/jsonrpc for gateway specific jsonrpc requests, and sharing the same http connection. See GatewayOptions for options that can be set.

func (*GatewayClient) Authenticate

func (c *GatewayClient) Authenticate(ctx context.Context) error

Authenticate will authenticate the client with the gateway. This is not necessary, as the client will automatically authenticate when needed, however it can be useful if the client desires to control when the authentication occurs / wants to manually force re-authentication.

func (*GatewayClient) Call

func (c *GatewayClient) Call(ctx context.Context, dbid string, action string, inputs []any) (*clientType.CallResult, error)

Call call an action. It returns the result records. If authentication is needed, it will call the gatewaySigner to sign the authentication message.

func (*GatewayClient) CallAction

func (c *GatewayClient) CallAction(ctx context.Context, dbid string, action string, inputs []any) (*clientType.Records, error)

CallAction calls an action. It returns the result records. If authentication is needed, Deprecated: Use Call instead.

func (*GatewayClient) GetAuthCookie

func (c *GatewayClient) GetAuthCookie() (cookie *http.Cookie, found bool)

GetAuthCookie returns the authentication cookie currently being used. If no authentication cookie is being used, it returns nil, false.

func (*GatewayClient) SetAuthCookie

func (c *GatewayClient) SetAuthCookie(cookie *http.Cookie) error

SetAuthCookie sets the authentication cookie to be used. If the cookie is not valid for the client target, it returns an error. It will overwrite any existing authentication cookie.

type GatewayOptions

type GatewayOptions struct {
	clientType.Options

	// AuthSignFunc is a function that will be used to sign gateway
	// authentication messages. By default, it's set to just sign the message
	// using the client's signer.
	AuthSignFunc GatewayAuthSignFunc

	// AuthCookieHandler is a function that will be called whenever a cookie is
	// being set to cookie jar. No default is set.
	AuthCookieHandler func(*http.Cookie) error
}

GatewayOptions are options that can be set for the gateway client

func DefaultOptions

func DefaultOptions() *GatewayOptions

DefaultOptions returns the default options for the gateway client.

func (*GatewayOptions) Apply

func (c *GatewayOptions) Apply(opt *GatewayOptions)

Apply applies the passed options to the receiver.