python sdk work

sdk/golang/examples/pastebin/README.md

@@ -0,0 +1,117 @@
+# "pastebin" SDK Example
+
+This `pastebin` example is a minimal `zrok` SDK application that implements a wormhole that makes redirecting file contents between multiple `zrok` environments very easy.
+
+The `pastebin` example is split into two separate commands. The `copyto` command takes a copy buffer from standard input. You can use it like this:
+
+```
+$ echo "this is a pastebin test" | copyto
+access your pastebin using 'pastefrom b46p9j82z81f'
+```
+
+And then using another terminal window, you can access your pastebin data like this:
+
+```
+$ pastefrom b46p9j82z81f
+this is a pastebin test
+```
+
+## The `copyto` Implementation
+
+The `copyto` utility is an illustration of how to implement an application that creates a share and exposes it to the `zrok` network. Let's look at each section of the implementation:
+
+```go
+	data, err := loadData()
+	if err != nil {
+		panic(err)
+	}
+```
+
+This first block of code is responsible for calling the `loadData` function, which loads the pastebin with data from `os.Stdin`.
+
+All SDK applications need to load the user's "root" from the `environment` package, like this:
+
+```go
+	root, err := environment.LoadRoot()
+	if err != nil {
+		panic(err)
+	}
+```
+
+The `root` is a structure that contains all of the user's environment detail and allows the SDK application to access the `zrok` service instance and the underlying OpenZiti network.
+
+Next, `copyto` will create a `zrok` share:
+
+```go
+	shr, err := sdk.CreateShare(root, &sdk.ShareRequest{
+		BackendMode: sdk.TcpTunnelBackendMode,
+		ShareMode:   sdk.PrivateShareMode,
+		Target:      "pastebin",
+	})
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Printf("access your pastebin using 'pastefrom %v'\n", shr.Token)
+```
+
+The `sdk.CreateShare` call uses the loaded `environment` root along with the details of the share request (`sdk.ShareRequest`) to create the share that will be used to access the `pastebin`.
+
+For the `pastebin` application, we're using a `sdk.TcpTunnelBackendMode` backend mode (we're just using a single network connection that implements a reliable byte stream, so TCP works great). Tunnel backends only work with `private` shares as of `zrok` `v0.4`, so we're using  `sdk.PrivateShareMode`. 
+
+We'll set the `Target` to be `pastebin`, as that's just metadata describing the application.
+
+Finally, we emit the share token so the user can access the `pastebin` using the `pastefrom` command.
+
+Next, we'll use the SDK to create a listener for this share:
+
+```go
+	listener, err := sdk.NewListener(shr.Token, root)
+	if err != nil {
+		panic(err)
+	}
+```
+
+The `sdk.NewListener` establishes a network listener for the newly created share. This listener works just like a `net.Listener`.
+
+Next, we're going to add a shutdown hook so that `copyto` will delete the share when the application is terminated using `^C`:
+
+```go
+	c := make(chan os.Signal)
+	signal.Notify(c, os.Interrupt, syscall.SIGTERM)
+	go func() {
+		<-c
+		if err := sdk.DeleteShare(root, shr); err != nil {
+			panic(err)
+		}
+		_ = listener.Close()
+		os.Exit(0)
+	}()
+```
+
+This anonymous function runs waiting for a signal to exit. When that is received, it runs the `sdk.DeleteShare` function to remove the share that was created. This is how ephemeral shares work for the `zrok share` commands as well.
+
+And finally, we run in an infinite loop waiting for requests for the `pastebin` data from the network:
+
+```go
+	for {
+		if conn, err := listener.Accept(); err == nil {
+			go handle(conn, data)
+		} else {
+			panic(err)
+		}
+	}	
+```
+
+## The "pastefrom" Implementation
+
+The `pastefrom` application works very similarly to `copyto`. The primary difference is that it "dials" the share through the SDK using `sdk.NewDialer`, which returns a `net.Conn`:
+
+```go
+	conn, err := sdk.NewDialer(shrToken, root)
+	if err != nil {
+		panic(err)
+	}
+```
+
+When this `sdk.NewDialer` function returns without an error, a bidirectional `net.Conn` has been established between the `copyto` "server" and the `pastefrom` "client". `pastefrom` then just reads the available data from the `net.Conn` and emits it to `os.Stdout`.

sdk/golang/examples/pastebin/cmd/copyto/main.go

@@ -0,0 +1,86 @@
+package main
+
+import (
+	"errors"
+	"fmt"
+	"github.com/michaelquigley/pfxlog"
+	"github.com/openziti/zrok/environment"
+	"github.com/openziti/zrok/sdk/golang/sdk"
+	"github.com/sirupsen/logrus"
+	"io"
+	"net"
+	"os"
+	"os/signal"
+	"syscall"
+)
+
+func init() {
+	pfxlog.GlobalInit(logrus.WarnLevel, pfxlog.DefaultOptions())
+}
+
+func main() {
+	data, err := loadData()
+	if err != nil {
+		panic(err)
+	}
+
+	root, err := environment.LoadRoot()
+	if err != nil {
+		panic(err)
+	}
+
+	shr, err := sdk.CreateShare(root, &sdk.ShareRequest{
+		BackendMode: sdk.TcpTunnelBackendMode,
+		ShareMode:   sdk.PrivateShareMode,
+		Target:      "pastebin",
+	})
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Printf("access your pastebin using 'pastefrom %v'\n", shr.Token)
+
+	listener, err := sdk.NewListener(shr.Token, root)
+	if err != nil {
+		panic(err)
+	}
+
+	c := make(chan os.Signal)
+	signal.Notify(c, os.Interrupt, syscall.SIGTERM)
+	go func() {
+		<-c
+		if err := sdk.DeleteShare(root, shr); err != nil {
+			panic(err)
+		}
+		_ = listener.Close()
+		os.Exit(0)
+	}()
+
+	for {
+		if conn, err := listener.Accept(); err == nil {
+			go handle(conn, data)
+		} else {
+			panic(err)
+		}
+	}
+}
+
+func loadData() ([]byte, error) {
+	stat, _ := os.Stdin.Stat()
+	if stat.Mode()&os.ModeCharDevice == 0 {
+		data, err := io.ReadAll(os.Stdin)
+		if err != nil {
+			return nil, err
+		}
+		return data, nil
+	} else {
+		return nil, errors.New("'copyto' requires input from stdin; direct your paste buffer into stdin")
+	}
+}
+
+func handle(conn net.Conn, data []byte) {
+	_, err := conn.Write(data)
+	if err != nil {
+		fmt.Printf("error: %v\n", err)
+	}
+}

sdk/golang/examples/pastebin/cmd/pastefrom/main.go

@@ -0,0 +1,48 @@
+package main
+
+import (
+	"fmt"
+	"github.com/openziti/zrok/environment"
+	"github.com/openziti/zrok/sdk/golang/sdk"
+	"os"
+)
+
+const MAX_PASTE_SIZE = 64 * 1024
+
+func main() {
+	if len(os.Args) < 2 {
+		panic("usage: pastefrom <shrToken>")
+	}
+	shrToken := os.Args[1]
+
+	root, err := environment.LoadRoot()
+	if err != nil {
+		panic(err)
+	}
+
+	acc, err := sdk.CreateAccess(root, &sdk.AccessRequest{ShareToken: shrToken})
+	if err != nil {
+		panic(err)
+	}
+	defer func() {
+		if err := sdk.DeleteAccess(root, acc); err != nil {
+			panic(err)
+		}
+	}()
+
+	conn, err := sdk.NewDialer(shrToken, root)
+	if err != nil {
+		panic(err)
+	}
+	defer func() {
+		_ = conn.Close()
+	}()
+
+	buf := make([]byte, MAX_PASTE_SIZE)
+	n, err := conn.Read(buf)
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Printf(string(buf[:n]))
+}

sdk/golang/sdk/access.go

@@ -0,0 +1,56 @@
+package sdk
+
+import (
+	httptransport "github.com/go-openapi/runtime/client"
+	"github.com/openziti/zrok/environment/env_core"
+	"github.com/openziti/zrok/rest_client_zrok/share"
+	"github.com/openziti/zrok/rest_model_zrok"
+	"github.com/pkg/errors"
+)
+
+func CreateAccess(root env_core.Root, request *AccessRequest) (*Access, error) {
+	if !root.IsEnabled() {
+		return nil, errors.New("environment is not enabled; enable with 'zrok enable' first!")
+	}
+
+	out := share.NewAccessParams()
+	out.Body = &rest_model_zrok.AccessRequest{
+		ShrToken: request.ShareToken,
+		EnvZID:   root.Environment().ZitiIdentity,
+	}
+
+	zrok, err := root.Client()
+	if err != nil {
+		return nil, errors.Wrap(err, "error getting zrok client")
+	}
+	auth := httptransport.APIKeyAuth("X-TOKEN", "header", root.Environment().Token)
+
+	in, err := zrok.Share.Access(out, auth)
+	if err != nil {
+		return nil, errors.Wrap(err, "unable to create access")
+	}
+
+	return &Access{Token: in.Payload.FrontendToken, ShareToken: request.ShareToken, BackendMode: BackendMode(in.Payload.BackendMode)}, nil
+}
+
+func DeleteAccess(root env_core.Root, acc *Access) error {
+	out := share.NewUnaccessParams()
+	out.Body = &rest_model_zrok.UnaccessRequest{
+		FrontendToken: acc.Token,
+		ShrToken:      acc.ShareToken,
+		EnvZID:        root.Environment().ZitiIdentity,
+	}
+
+	zrok, err := root.Client()
+	if err != nil {
+		return errors.Wrap(err, "error getting zrok client")
+	}
+	auth := httptransport.APIKeyAuth("X-TOKEN", "header", root.Environment().Token)
+
+	_, err = zrok.Share.Unaccess(out, auth)
+	if err != nil {
+		return errors.Wrap(err, "error deleting access")
+	}
+
+	return nil
+}

sdk/golang/sdk/config.go

@@ -0,0 +1,39 @@
+package sdk
+
+import "github.com/pkg/errors"
+
+const ZrokProxyConfig = "zrok.proxy.v1"
+
+type FrontendConfig struct {
+	AuthScheme AuthScheme       `json:"auth_scheme"`
+	BasicAuth  *BasicAuthConfig `json:"basic_auth"`
+	OauthAuth  *OauthConfig     `json:"oauth"`
+}
+
+type BasicAuthConfig struct {
+	Users []*AuthUserConfig `json:"users"`
+}
+
+type AuthUserConfig struct {
+	Username string `json:"username"`
+	Password string `json:"password"`
+}
+
+type OauthConfig struct {
+	Provider                   string   `json:"provider"`
+	EmailDomains               []string `json:"email_domains"`
+	AuthorizationCheckInterval string   `json:"authorization_check_interval"`
+}
+
+func ParseAuthScheme(authScheme string) (AuthScheme, error) {
+	switch authScheme {
+	case string(None):
+		return None, nil
+	case string(Basic):
+		return Basic, nil
+	case string(Oauth):
+		return Oauth, nil
+	default:
+		return None, errors.Errorf("unknown auth scheme '%v'", authScheme)
+	}
+}

sdk/golang/sdk/dialer.go

@@ -0,0 +1,32 @@
+package sdk
+
+import (
+	"github.com/openziti/sdk-golang/ziti"
+	"github.com/openziti/sdk-golang/ziti/edge"
+	"github.com/openziti/zrok/environment/env_core"
+	"github.com/pkg/errors"
+)
+
+func NewDialer(shrToken string, root env_core.Root) (edge.Conn, error) {
+	zif, err := root.ZitiIdentityNamed(root.EnvironmentIdentityName())
+	if err != nil {
+		return nil, errors.Wrap(err, "error getting ziti identity path")
+	}
+
+	zcfg, err := ziti.NewConfigFromFile(zif)
+	if err != nil {
+		return nil, errors.Wrap(err, "error loading ziti identity")
+	}
+
+	zctx, err := ziti.NewContext(zcfg)
+	if err != nil {
+		return nil, errors.Wrap(err, "error getting ziti context")
+	}
+
+	conn, err := zctx.Dial(shrToken)
+	if err != nil {
+		return nil, errors.Wrapf(err, "error dialing '%v'", shrToken)
+	}
+
+	return conn, nil
+}

sdk/golang/sdk/listener.go

@@ -0,0 +1,37 @@
+package sdk
+
+import (
+	"github.com/openziti/sdk-golang/ziti"
+	"github.com/openziti/sdk-golang/ziti/edge"
+	"github.com/openziti/zrok/environment/env_core"
+	"github.com/pkg/errors"
+	"time"
+)
+
+func NewListener(shrToken string, root env_core.Root) (edge.Listener, error) {
+	return NewListenerWithOptions(shrToken, root, &ziti.ListenOptions{ConnectTimeout: 30 * time.Second, MaxConnections: 64})
+}
+
+func NewListenerWithOptions(shrToken string, root env_core.Root, opts *ziti.ListenOptions) (edge.Listener, error) {
+	zif, err := root.ZitiIdentityNamed(root.EnvironmentIdentityName())
+	if err != nil {
+		return nil, errors.Wrap(err, "error getting ziti identity path")
+	}
+
+	zcfg, err := ziti.NewConfigFromFile(zif)
+	if err != nil {
+		return nil, errors.Wrap(err, "error loading ziti identity")
+	}
+
+	zctx, err := ziti.NewContext(zcfg)
+	if err != nil {
+		return nil, errors.Wrap(err, "error getting ziti context")
+	}
+
+	listener, err := zctx.ListenWithOptions(shrToken, opts)
+	if err != nil {
+		return nil, errors.Wrap(err, "error creating listener")
+	}
+
+	return listener, nil
+}

sdk/golang/sdk/model.go

@@ -0,0 +1,65 @@
+package sdk
+
+import "time"
+
+type BackendMode string
+
+const (
+	ProxyBackendMode     BackendMode = "proxy"
+	WebBackendMode       BackendMode = "web"
+	TcpTunnelBackendMode BackendMode = "tcpTunnel"
+	UdpTunnelBackendMode BackendMode = "udpTunnel"
+	CaddyBackendMode     BackendMode = "caddy"
+)
+
+type ShareMode string
+
+const (
+	PrivateShareMode ShareMode = "private"
+	PublicShareMode  ShareMode = "public"
+)
+
+type ShareRequest struct {
+	BackendMode                     BackendMode
+	ShareMode                       ShareMode
+	Target                          string
+	Frontends                       []string
+	BasicAuth                       []string
+	OauthProvider                   string
+	OauthEmailDomains               []string
+	OauthAuthorizationCheckInterval time.Duration
+}
+
+type Share struct {
+	Token             string
+	FrontendEndpoints []string
+}
+
+type AccessRequest struct {
+	ShareToken string
+}
+
+type Access struct {
+	Token       string
+	ShareToken  string
+	BackendMode BackendMode
+}
+
+type Metrics struct {
+	Namespace string
+	Sessions  map[string]SessionMetrics
+}
+
+type SessionMetrics struct {
+	BytesRead    int64
+	BytesWritten int64
+	LastUpdate   int64
+}
+
+type AuthScheme string
+
+const (
+	None  AuthScheme = "none"
+	Basic AuthScheme = "basic"
+	Oauth AuthScheme = "oauth"
+)

sdk/golang/sdk/overview.go

@@ -0,0 +1,35 @@
+package sdk
+
+import (
+	"errors"
+	"fmt"
+	"github.com/openziti/zrok/environment/env_core"
+	"io"
+	"net/http"
+)
+
+func Overview(root env_core.Root) (string, error) {
+	if !root.IsEnabled() {
+		return "", errors.New("environment is not enabled; enable with 'zrok enable' first!")
+	}
+
+	client := &http.Client{}
+	apiEndpoint, _ := root.ApiEndpoint()
+	req, err := http.NewRequest("GET", fmt.Sprintf("%v/api/v1/overview", apiEndpoint), nil)
+	if err != nil {
+		return "", err
+	}
+	req.Header.Add("X-TOKEN", root.Environment().Token)
+	resp, err := client.Do(req)
+	if err != nil {
+		return "", err
+	}
+
+	json, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return "", err
+	}
+	_ = resp.Body.Close()
+
+	return string(json), nil
+}

sdk/golang/sdk/share.go

@@ -0,0 +1,109 @@
+package sdk
+
+import (
+	httptransport "github.com/go-openapi/runtime/client"
+	"github.com/openziti/zrok/environment/env_core"
+	"github.com/openziti/zrok/rest_client_zrok/share"
+	"github.com/openziti/zrok/rest_model_zrok"
+	"github.com/pkg/errors"
+	"strings"
+)
+
+func CreateShare(root env_core.Root, request *ShareRequest) (*Share, error) {
+	if !root.IsEnabled() {
+		return nil, errors.New("environment is not enabled; enable with 'zrok enable' first!")
+	}
+
+	var err error
+	var out *share.ShareParams
+
+	switch request.ShareMode {
+	case PrivateShareMode:
+		out = newPrivateShare(root, request)
+	case PublicShareMode:
+		out = newPublicShare(root, request)
+	default:
+		return nil, errors.Errorf("unknown share mode '%v'", request.ShareMode)
+	}
+
+	if len(request.BasicAuth) > 0 {
+		out.Body.AuthScheme = string(Basic)
+		for _, basicAuthUser := range request.BasicAuth {
+			tokens := strings.Split(basicAuthUser, ":")
+			if len(tokens) == 2 {
+				out.Body.AuthUsers = append(out.Body.AuthUsers, &rest_model_zrok.AuthUser{Username: strings.TrimSpace(tokens[0]), Password: strings.TrimSpace(tokens[1])})
+			} else {
+				return nil, errors.Errorf("invalid username:password '%v'", basicAuthUser)
+			}
+		}
+	}
+
+	if request.OauthProvider != "" {
+		out.Body.AuthScheme = string(Oauth)
+	}
+
+	zrok, err := root.Client()
+	if err != nil {
+		return nil, errors.Wrap(err, "error getting zrok client")
+	}
+	auth := httptransport.APIKeyAuth("X-TOKEN", "header", root.Environment().Token)
+
+	in, err := zrok.Share.Share(out, auth)
+	if err != nil {
+		return nil, errors.Wrap(err, "unable to create share")
+	}
+
+	return &Share{
+		Token:             in.Payload.ShrToken,
+		FrontendEndpoints: in.Payload.FrontendProxyEndpoints,
+	}, nil
+}
+
+func newPrivateShare(root env_core.Root, request *ShareRequest) *share.ShareParams {
+	req := share.NewShareParams()
+	req.Body = &rest_model_zrok.ShareRequest{
+		EnvZID:               root.Environment().ZitiIdentity,
+		ShareMode:            string(request.ShareMode),
+		BackendMode:          string(request.BackendMode),
+		BackendProxyEndpoint: request.Target,
+		AuthScheme:           string(None),
+	}
+	return req
+}
+
+func newPublicShare(root env_core.Root, request *ShareRequest) *share.ShareParams {
+	req := share.NewShareParams()
+	req.Body = &rest_model_zrok.ShareRequest{
+		EnvZID:                          root.Environment().ZitiIdentity,
+		ShareMode:                       string(request.ShareMode),
+		FrontendSelection:               request.Frontends,
+		BackendMode:                     string(request.BackendMode),
+		BackendProxyEndpoint:            request.Target,
+		AuthScheme:                      string(None),
+		OauthEmailDomains:               request.OauthEmailDomains,
+		OauthProvider:                   request.OauthProvider,
+		OauthAuthorizationCheckInterval: request.OauthAuthorizationCheckInterval.String(),
+	}
+	return req
+}
+
+func DeleteShare(root env_core.Root, shr *Share) error {
+	req := share.NewUnshareParams()
+	req.Body = &rest_model_zrok.UnshareRequest{
+		EnvZID:   root.Environment().ZitiIdentity,
+		ShrToken: shr.Token,
+	}
+
+	zrok, err := root.Client()
+	if err != nil {
+		return errors.Wrap(err, "error getting zrok client")
+	}
+	auth := httptransport.APIKeyAuth("X-TOKEN", "header", root.Environment().Token)
+
+	_, err = zrok.Share.Unshare(req, auth)
+	if err != nil {
+		return errors.Wrap(err, "error deleting share")
+	}
+
+	return nil
+}