zrok2-build-debugging 22.0.2000008__py3-none-any.whl

zrok/model.py

@@ -0,0 +1,75 @@
+from dataclasses import dataclass, field
+
+BackendMode = str
+
+PROXY_BACKEND_MODE: BackendMode = "proxy"
+WEB_BACKEND_MODE: BackendMode = "web"
+TCP_TUNNEL_BACKEND_MODE: BackendMode = "tcpTunnel"
+UDP_TUNNEL_BACKEND_MODE: BackendMode = "udpTunnel"
+CADDY_BACKEND_MODE: BackendMode = "caddy"
+DRIVE_BACKEND_MODE: BackendMode = "drive"
+SOCKS_BACKEND_MODE: BackendMode = "socks"
+
+ShareMode = str
+
+PRIVATE_SHARE_MODE: ShareMode = "private"
+PUBLIC_SHARE_MODE: ShareMode = "public"
+
+PermissionMode = str
+
+OPEN_PERMISSION_MODE: PermissionMode = "open"
+CLOSED_PERMISSION_MODE: PermissionMode = "closed"
+
+
+@dataclass
+class ShareRequest:
+    BackendMode: BackendMode
+    ShareMode: ShareMode
+    Target: str
+    Frontends: list[str] = field(default_factory=list[str])
+    BasicAuth: list[str] = field(default_factory=list[str])
+    OauthProvider: str = ""
+    OauthEmailAddressPatterns: list[str] = field(default_factory=list[str])
+    OauthAuthorizationCheckInterval: str = ""
+    Reserved: bool = False
+    UniqueName: str = ""
+    PermissionMode: PermissionMode = OPEN_PERMISSION_MODE
+    AccessGrants: list[str] = field(default_factory=list[str])
+
+
+@dataclass
+class Share:
+    Token: str
+    FrontendEndpoints: list[str]
+
+
+@dataclass
+class AccessRequest:
+    ShareToken: str
+
+
+@dataclass
+class Access:
+    Token: str
+    ShareToken: str
+    BackendMode: BackendMode
+
+
+@dataclass
+class SessionMetrics:
+    BytesRead: int
+    BytesWritten: int
+    LastUpdate: int
+
+
+@dataclass
+class Metrics:
+    Namespace: str
+    Sessions: dict[str, SessionMetrics]
+
+
+AuthScheme = str
+
+AUTH_SCHEME_NONE: AuthScheme = "none"
+AUTH_SCHEME_BASIC: AuthScheme = "basic"
+AUTH_SCHEME_OAUTH: AuthScheme = "oauth"

zrok/overview.py

@@ -0,0 +1,77 @@
+import json
+from dataclasses import dataclass, field
+from typing import List
+
+import urllib3
+from zrok.environment.root import Root
+from zrok_api.models.environment import Environment
+from zrok_api.models.environment_and_resources import EnvironmentAndResources
+from zrok_api.models.share import Share
+
+
+@dataclass
+class Overview:
+    environments: List[EnvironmentAndResources] = field(default_factory=list)
+
+    @classmethod
+    def create(cls, root: Root) -> 'Overview':
+        if not root.IsEnabled():
+            raise Exception("environment is not enabled; enable with 'zrok enable' first!")
+
+        http = urllib3.PoolManager()
+        apiEndpoint = root.ApiEndpoint().endpoint
+        try:
+            response = http.request(
+                'GET',
+                apiEndpoint + "/api/v2/overview",
+                headers={
+                    "X-TOKEN": root.env.Token
+                })
+        except Exception as e:
+            raise Exception("unable to get account overview", e)
+
+        json_data = json.loads(response.data.decode('utf-8'))
+        overview = cls()
+
+        for env_data in json_data.get('environments', []):
+            env_dict = env_data['environment']
+            # Map the JSON keys to the Environment class parameters
+            environment = Environment(
+                description=env_dict.get('description'),
+                host=env_dict.get('host'),
+                address=env_dict.get('address'),
+                z_id=env_dict.get('zId'),
+                activity=env_dict.get('activity'),
+                limited=env_dict.get('limited'),
+                created_at=env_dict.get('createdAt'),
+                updated_at=env_dict.get('updatedAt')
+            )
+
+            # Create Shares object from share data
+            share_list = []
+            for share_data in env_data.get('shares', []):
+                share = Share(
+                    share_token=share_data.get('shareToken'),
+                    z_id=share_data.get('zId'),
+                    share_mode=share_data.get('shareMode'),
+                    backend_mode=share_data.get('backendMode'),
+                    frontend_selection=share_data.get('frontendSelection'),
+                    frontend_endpoint=share_data.get('frontendEndpoint'),
+                    backend_proxy_endpoint=share_data.get('backendProxyEndpoint'),
+                    reserved=share_data.get('reserved'),
+                    activity=share_data.get('activity'),
+                    limited=share_data.get('limited'),
+                    created_at=share_data.get('createdAt'),
+                    updated_at=share_data.get('updatedAt')
+                )
+                share_list.append(share)
+
+            # Create EnvironmentAndResources object
+            env_resources = EnvironmentAndResources(
+                environment=environment,
+                shares=share_list,
+                frontends=[]
+            )
+            overview.environments.append(env_resources)
+
+        return overview

zrok/proxy.py

@@ -0,0 +1,203 @@
+"""
+Proxy share management functionality for the zrok SDK.
+"""
+
+import atexit
+import logging
+import urllib.parse
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+import requests
+from flask import Flask, Response, request
+from waitress import serve
+from zrok.environment.root import Root
+from zrok.model import (PROXY_BACKEND_MODE, PUBLIC_SHARE_MODE, PRIVATE_SHARE_MODE, Share,
+                        ShareRequest)
+from zrok.overview import Overview
+from zrok.share import CreateShare, ReleaseReservedShare
+
+import zrok
+
+logger = logging.getLogger(__name__)
+
+# List of hop-by-hop headers that should not be returned to the viewer
+HOP_BY_HOP_HEADERS = {
+    'connection',
+    'keep-alive',
+    'proxy-authenticate',
+    'proxy-authorization',
+    'te',
+    'trailers',
+    'transfer-encoding',
+    'upgrade'
+}
+
+# The proxy only listens on the zrok socket, the port used to initialize the Waitress server is not actually bound or
+# listening
+DUMMY_PORT = 18081
+
+
+@dataclass
+class ProxyShare:
+    """Represents a proxy share with its configuration and state."""
+    root: Root
+    share: Share
+    target: str
+    unique_name: Optional[str] = None
+    _cleanup_registered: bool = False
+    _app: Optional[Flask] = None
+    verify_ssl: bool = True
+
+    @classmethod
+    def create(cls, root: Root, target: str, share_mode: str = PUBLIC_SHARE_MODE, unique_name: Optional[str] = None,
+               frontends: Optional[List[str]] = None, verify_ssl: bool = True) -> 'ProxyShare':
+        """
+        Create a new proxy share, handling reservation and cleanup logic based on unique_name.
+
+        Args:
+            root: The zrok root environment
+            target: Target URL or service to proxy to
+            unique_name: Optional unique name for a reserved share
+            frontends: Optional list of frontends to use, takes precedence over root's default_frontend
+            verify_ssl: Whether to verify SSL certificates when forwarding requests.
+
+        Returns:
+            ProxyShare instance configured with the created share
+        """
+        # First check if we have an existing reserved share with this name
+        if unique_name:
+            existing_share = cls._find_existing_share(root, unique_name)
+            if existing_share:
+                logger.debug(f"Found existing share with token: {existing_share.Token}")
+                return cls(
+                    root=root,
+                    share=existing_share,
+                    target=target,
+                    unique_name=unique_name,
+                    verify_ssl=verify_ssl
+                )
+
+        # Compose the share request
+        share_frontends = []
+        if share_mode == PUBLIC_SHARE_MODE:
+            if frontends:
+                share_frontends = frontends
+            elif root.cfg and root.cfg.DefaultFrontend:
+                share_frontends = [root.cfg.DefaultFrontend]
+            else:
+                share_frontends = ['public']
+
+        share_request = ShareRequest(
+            BackendMode=PROXY_BACKEND_MODE,
+            ShareMode=share_mode,
+            Target=target,
+            Frontends=share_frontends,
+            Reserved=True
+        )
+        if unique_name:
+            share_request.UniqueName = unique_name
+
+        # Create the share
+        share = CreateShare(root=root, request=share_request)
+        if share_mode == PUBLIC_SHARE_MODE:
+            logger.debug(f"Created new proxy share with endpoints: {', '.join(share.FrontendEndpoints)}")
+        elif share_mode == PRIVATE_SHARE_MODE:
+            logger.debug(f"Created new private share with token: {share.Token}")
+
+        # Create class instance and setup cleanup-at-exit if we reserved a random share token
+        instance = cls(
+            root=root,
+            share=share,
+            target=target,
+            unique_name=unique_name,
+            verify_ssl=verify_ssl
+        )
+        if not unique_name:
+            instance.register_cleanup()
+        return instance
+
+    @staticmethod
+    def _find_existing_share(root: Root, unique_name: str) -> Optional[Share]:
+        """Find an existing share with the given unique name."""
+        overview = Overview.create(root=root)
+        for env in overview.environments:
+            if env.environment.z_id == root.env.ZitiIdentity:
+                for share in env.shares:
+                    if share.share_token == unique_name:
+                        return Share(Token=share.share_token, FrontendEndpoints=[share.frontend_endpoint])
+        return None
+
+    def register_cleanup(self):
+        """Register cleanup handler to release randomly generated shares on exit."""
+        if not self._cleanup_registered:
+            def cleanup():
+                try:
+                    ReleaseReservedShare(root=self.root, shr=self.share)
+                    logger.info(f"Share {self.share.Token} released")
+                except Exception as e:
+                    logger.error(f"Error during cleanup: {e}")
+
+            # Register for normal exit only
+            atexit.register(cleanup)
+            self._cleanup_registered = True
+            return cleanup  # Return the cleanup function for reuse
+
+    def _create_app(self) -> Flask:
+        """Create and configure the Flask app for proxying."""
+        app = Flask(__name__)
+
+        @app.route('/', defaults={'path': ''}, methods=['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'])
+        @app.route('/<path:path>', methods=['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'])
+        def proxy(path):
+            # Construct the target URL
+            url = urllib.parse.urljoin(self.target, path)
+
+            # Forward the request
+            resp = requests.request(
+                method=request.method,
+                url=url,
+                headers={key: value for (key, value) in request.headers
+                         if key.lower() not in HOP_BY_HOP_HEADERS},
+                data=request.get_data(),
+                cookies=request.cookies,
+                allow_redirects=False,
+                stream=True,
+                verify=self.verify_ssl
+            )
+
+            # Create the response
+            excluded_headers = HOP_BY_HOP_HEADERS.union({'host'})
+            headers = [(name, value) for (name, value) in resp.raw.headers.items()
+                       if name.lower() not in excluded_headers]
+
+            return Response(
+                resp.iter_content(chunk_size=10*1024),
+                status=resp.status_code,
+                headers=headers
+            )
+        return app
+
+    def run(self):
+        """Run the proxy server."""
+        if not self._app:
+            self._app = self._create_app()
+
+        zrok_opts: Dict[str, Any] = {}
+        zrok_opts['cfg'] = zrok.decor.Opts(root=self.root, shrToken=self.token, bindPort=DUMMY_PORT)
+
+        @zrok.decor.zrok(opts=zrok_opts)
+        def run_server():
+            serve(self._app, port=DUMMY_PORT, _quiet=True)
+
+        run_server()
+
+    @property
+    def endpoints(self) -> List[str]:
+        """Get the frontend endpoints for this share."""
+        return self.share.FrontendEndpoints
+
+    @property
+    def token(self) -> str:
+        """Get the share token."""
+        return self.share.Token

zrok/share.py

@@ -0,0 +1,199 @@
+from zrok_api.api import ShareApi
+from zrok.environment.root import Root
+from zrok_api.models.auth_user import AuthUser
+from zrok_api.models.share_request import ShareRequest
+from zrok_api.models.unshare_request import UnshareRequest
+import json
+from zrok_api.exceptions import ApiException
+import zrok.model as model
+
+
+class Share():
+    root: Root
+    request: model.ShareRequest
+    share: model.Share
+
+    def __init__(self, root: Root, request: model.ShareRequest):
+        self.root = root
+        self.request = request
+
+    def __enter__(self) -> model.Share:
+        self.share = CreateShare(root=self.root, request=self.request)
+        return self.share
+
+    def __exit__(self, exception_type, exception_value, exception_traceback):
+        if not self.request.Reserved:
+            DeleteShare(root=self.root, shr=self.share)
+
+
+def CreateShare(root: Root, request: model.ShareRequest) -> model.Share:
+    if not root.IsEnabled():
+        raise Exception("environment is not enabled; enable with 'zrok enable' first!")
+
+    match request.ShareMode:
+        case model.PRIVATE_SHARE_MODE:
+            out = __newPrivateShare(root, request)
+        case model.PUBLIC_SHARE_MODE:
+            out = __newPublicShare(root, request)
+        case _:
+            raise Exception("unknown share mode " + request.ShareMode)
+    out.reserved = request.Reserved
+    if request.Reserved:
+        out.unique_name = request.UniqueName
+
+    if len(request.BasicAuth) > 0:
+        out.auth_scheme = model.AUTH_SCHEME_BASIC
+        for pair in request.BasicAuth:
+            tokens = pair.split(":")
+            if len(tokens) == 2:
+                out.auth_users.append(AuthUser(username=tokens[0].strip(), password=tokens[1].strip()))
+            else:
+                raise Exception("invalid username:password pair: " + pair)
+
+    if request.OauthProvider != "":
+        out.auth_scheme = model.AUTH_SCHEME_OAUTH
+
+    try:
+        zrok = root.Client()
+    except Exception as e:
+        raise Exception("error getting zrok client", e)
+
+    try:
+        # Use share_with_http_info to get access to the HTTP info and handle custom response format
+        share_api = ShareApi(zrok)
+        # Add Accept header to handle the custom content type
+        custom_headers = {
+            'Accept': 'application/json, application/zrok.v1+json'
+        }
+
+        response_data = share_api.share_with_http_info(
+            body=out,
+            _headers=custom_headers
+        )
+
+        # Parse response
+        if hasattr(response_data, 'data') and response_data.data is not None:
+            res = response_data.data
+        else:
+            raise Exception("invalid response from server")
+
+    except ApiException as e:
+        # If it's a content type error, try to parse the raw JSON
+        if "Unsupported content type: application/zrok.v1+json" in str(e) and hasattr(e, 'body'):
+            try:
+                # Parse the response body directly
+                res_dict = json.loads(e.body)
+                # Create a response object with the expected fields
+
+                class ShareResponse:
+                    def __init__(self, share_token, frontend_proxy_endpoints):
+                        self.share_token = share_token
+                        self.frontend_proxy_endpoints = frontend_proxy_endpoints
+
+                res = ShareResponse(
+                    share_token=res_dict.get('shareToken', ''),
+                    frontend_proxy_endpoints=res_dict.get('frontendProxyEndpoints', [])
+                )
+            except (json.JSONDecodeError, ValueError, AttributeError) as json_err:
+                raise Exception(f"unable to parse API response: {str(json_err)}") from e
+        else:
+            raise Exception("unable to create share", e)
+    except Exception as e:
+        raise Exception("unable to create share", e)
+
+    return model.Share(Token=res.share_token,
+                       FrontendEndpoints=res.frontend_proxy_endpoints)
+
+
+def __newPrivateShare(root: Root, request: model.ShareRequest) -> ShareRequest:
+    return ShareRequest(env_zid=root.env.ZitiIdentity,
+                        share_mode=request.ShareMode,
+                        backend_mode=request.BackendMode,
+                        backend_proxy_endpoint=request.Target,
+                        auth_scheme=model.AUTH_SCHEME_NONE,
+                        permission_mode=request.PermissionMode,
+                        access_grants=request.AccessGrants
+                        )
+
+
+def __newPublicShare(root: Root, request: model.ShareRequest) -> ShareRequest:
+    ret = ShareRequest(env_zid=root.env.ZitiIdentity,
+                       share_mode=request.ShareMode,
+                       frontend_selection=request.Frontends,
+                       backend_mode=request.BackendMode,
+                       backend_proxy_endpoint=request.Target,
+                       auth_scheme=model.AUTH_SCHEME_NONE,
+                       oauth_email_domains=request.OauthEmailAddressPatterns,
+                       oauth_authorization_check_interval=request.OauthAuthorizationCheckInterval,
+                       permission_mode=request.PermissionMode,
+                       access_grants=request.AccessGrants
+                       )
+    if request.OauthProvider != "":
+        ret.oauth_provider = request.OauthProvider
+
+    return ret
+
+
+def DeleteShare(root: Root, shr: model.Share):
+    req = UnshareRequest(env_zid=root.env.ZitiIdentity,
+                         share_token=shr.Token)
+
+    try:
+        zrok = root.Client()
+    except Exception as e:
+        raise Exception("error getting zrok client", e)
+
+    try:
+        # Add Accept header to handle the custom content type
+        share_api = ShareApi(zrok)
+        custom_headers = {
+            'Accept': 'application/json, application/zrok.v1+json'
+        }
+
+        # Use unshare_with_http_info to get access to the HTTP info
+        share_api.unshare_with_http_info(
+            body=req,
+            _headers=custom_headers
+        )
+    except ApiException as e:
+        # If it's a content type error but the operation was likely successful, don't propagate the error
+        if "Unsupported content type: application/zrok.v1+json" in str(e) and (200 <= e.status <= 299):
+            # The operation was likely successful despite the content type error
+            pass
+        else:
+            raise Exception("error deleting share", e)
+    except Exception as e:
+        raise Exception("error deleting share", e)
+
+
+def ReleaseReservedShare(root: Root, shr: model.Share):
+    req = UnshareRequest(env_zid=root.env.ZitiIdentity,
+                         share_token=shr.Token,
+                         reserved=True)
+
+    try:
+        zrok = root.Client()
+    except Exception as e:
+        raise Exception("error getting zrok client", e)
+
+    try:
+        # Add Accept header to handle the custom content type
+        share_api = ShareApi(zrok)
+        custom_headers = {
+            'Accept': 'application/json, application/zrok.v1+json'
+        }
+
+        # Use unshare_with_http_info to get access to the HTTP info
+        share_api.unshare_with_http_info(
+            body=req,
+            _headers=custom_headers
+        )
+    except ApiException as e:
+        # If it's a content type error but the operation was likely successful, don't propagate the error
+        if "Unsupported content type: application/zrok.v1+json" in str(e) and (200 <= e.status <= 299):
+            # The operation was likely successful despite the content type error
+            pass
+        else:
+            raise Exception("error releasing share", e)
+    except Exception as e:
+        raise Exception("error releasing share", e)

zrok2_build_debugging-22.0.2000008.dist-info/METADATA

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: zrok2-build-debugging
+Version: 22.0.2000008
+Summary: zrok2
+Home-page: https://github.com/openziti/zrok
+Author: NetFoundry
+Author-email: developers@openziti.org
+License: Apache 2.0
+Project-URL: Source, https://github.com/openziti/zrok
+Project-URL: Tracker, https://github.com/openziti/zrok/issues
+Project-URL: Discussion, https://openziti.discourse.group/
+Keywords: zrok,zrok2
+Requires-Python: >3.10.0
+Description-Content-Type: text/markdown
+Requires-Dist: openziti>=1.0.0
+Requires-Dist: urllib3>=2.1.0
+Dynamic: description
+Dynamic: keywords
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+    Geo-scale, next-generation peer-to-peer sharing platform built on top of OpenZiti.
+