@devkong/cli-nx 0.0.67-alpha.3 → 0.0.67-alpha.30

package/src/generators/preset/files/python/README.md

@@ -0,0 +1,262 @@
+# Kong Extension
+
+Welcome to the Kong extension development workspace!
+
+To have a better experience, open this file in preview mode of your IDE.
+
+### Prerequisites
+
+Before you start, make sure you have the following installed depending on your OS:
+
+[▶ Windows](#windows-setup)
+
+[▶ Ubuntu](#ubuntu-setup)
+
+[▶ macOS](#macos-setup)
+
+To verify the installation and check the versions, run the following commands:
+
+```shell script
+node --version
+docker info
+```
+
+### Getting Started
+
+1. Make sure you're in the terminal and inside the extension folder you generated
+2. Run the following commands in your terminal:
+
+```shell script
+# configure the base Kong URL (e.g., https://sandbox.kong.dev.app-dts.net)
+kong configure
+
+# install Python dependencies from requirements.txt
+kong install --verbose
+```
+
+### Publish a New Version
+
+To automatically tag your code with an incremented version number (e.g., 1, 2, 3), run:
+
+```shell script
+kong publish-version --verbose
+```
+
+### List Available Versions
+
+To see all available versions of your extension, run:
+
+```shell script
+kong list-versions
+```
+
+### Assign an Alias to a Version
+
+You can assign an alias (e.g., stable, beta) to a specific version. This alias will appear in the UI as a separate step in the workflow. For example, to assign the alias stable to version 1, use:
+
+```shell script
+# send all traffic to version 1
+kong set-alias stable 1
+
+# split live traffic: 80% to version 1, 20% to version 2 (weights must add up to 100)
+kong set-alias stable 1:80 2:20
+
+# same split, plus mirror traffic to version 3 as a shadow (it serves no live traffic)
+kong set-alias stable 1:80 2:20 3:shadow
+```
+
+### Using a Custom Profile
+
+If you're developing an extension that will be used in different regions (or need to work with a specific profile), you can create a new profile using `kong configure`. Then, include the `--profile <name>` parameter when running the publish-version and set-alias commands to use the desired profile.
+
+### Update CLI
+
+To install the latest version of the CLI, run:
+
+```shell script
+npm i -g @devkong/cli@latest
+```
+
+### Setup
+
+<details id="windows-setup">
+<summary><strong>Windows</strong></summary>
+
+### Install Windows Subsystem for Linux (WSL2)
+
+1. Open PowerShell as Administrator.
+2. Run the following command to install WSL and set WSL2 as the default version:
+   ```powershell
+   wsl --install
+   ```
+3. Restart your computer if prompted.
+4. After restarting, install a preferred Linux distribution (e.g., Ubuntu) by running:
+   ```powershell
+   wsl --install -d Ubuntu
+   ```
+
+### Install Docker within WSL2
+
+1. Download Docker Desktop for Windows from [Docker's official website](https://www.docker.com/products/docker-desktop).
+2. Run the installer and follow the setup instructions.
+3. During installation, ensure the "Use the WSL 2 based engine" option is selected.
+4. Once installed, open Docker Desktop, go to Settings > General, and enable "Use WSL 2 based engine" if it isn't already enabled.
+5. Confirm Docker is working in your WSL2 distribution (e.g., Ubuntu) by running:
+   ```bash
+   docker --version
+   ```
+
+### Install Node.js and npm on Windows Host
+
+1. Download the Node.js installer for Windows from the [official Node.js website](https://nodejs.org/).
+2. Run the installer, making sure to include the npm package manager during installation.
+3. Verify installation by opening a new Command Prompt and running:
+   ```cmd
+   node -v
+   npm -v
+   ```
+
+### Install Python on Windows Host
+
+1. Download the Python installer (version >= 3.10) for Windows from the [official Python website](https://www.python.org/downloads/windows/).
+2. Run the installer, making sure to check "Add Python to PATH" during setup.
+3. Verify installation by running:
+   ```cmd
+   python --version
+   pip --version
+   ```
+
+### Install Poetry on Windows Host
+
+1. Open Command Prompt or PowerShell.
+2. Run the following command:
+   ```powershell
+   (Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -
+   ```
+3. Add Poetry to your PATH:
+   ```powershell
+   $env:Path += ";$env:USERPROFILE\.poetry\bin"
+   ```
+4. Verify installation:
+   ```powershell
+   poetry --version
+   ```
+
+</details>
+
+<details id="ubuntu-setup">
+<summary><strong>Ubuntu</strong></summary>
+
+### Install Docker
+
+1. Follow the installation instructions on [Docker's official website](https://docs.docker.com/engine/install/ubuntu/).
+2. Start Docker and enable it to start on boot:
+   ```bash
+   sudo systemctl start docker
+   sudo systemctl enable docker
+   ```
+
+### Install Node.js and npm
+
+1. Run the following commands:
+   ```bash
+   sudo apt update
+   sudo apt install -y nodejs npm
+   ```
+2. Verify installation:
+   ```bash
+   node -v
+   npm -v
+   ```
+
+### Install Python
+
+1. Run the following commands:
+   ```bash
+   sudo apt update
+   sudo apt install -y python3 python3-pip
+   ```
+2. Verify installation:
+   ```bash
+   python3 --version
+   pip3 --version
+   ```
+
+### Install Poetry
+
+1. Run the following command:
+   ```bash
+   curl -sSL https://install.python-poetry.org | python3 -
+   ```
+2. Add Poetry to your PATH:
+   ```bash
+   export PATH="$HOME/.local/bin:$PATH"
+   ```
+3. Reload the shell:
+   ```bash
+   source ~/.bashrc
+   ```
+4. Verify installation:
+   ```bash
+   poetry --version
+   ```
+
+</details>
+
+<details id="macos-setup">
+<summary><strong>macOS</strong></summary>
+
+To emulate a Linux platform, you need to install Rosetta:
+
+```shell script
+softwareupdate --install-rosetta
+```
+
+### Install Docker
+
+1. Download and install Docker Desktop for Mac from [Docker's official website](https://www.docker.com/products/docker-desktop).
+
+### Install Node.js and npm
+
+1. Use Homebrew to install:
+   ```bash
+   brew install node
+   ```
+2. Verify installation:
+   ```bash
+   node -v
+   npm -v
+   ```
+
+### Install Python
+
+1. Use Homebrew to install:
+   ```bash
+   brew install python
+   ```
+2. Verify installation:
+   ```bash
+   python3 --version
+   pip3 --version
+   ```
+
+### Install Poetry
+
+1. Run the following command:
+   ```bash
+   curl -sSL https://install.python-poetry.org | python3 -
+   ```
+2. Add Poetry to your PATH:
+   ```bash
+   export PATH="$HOME/.local/bin:$PATH"
+   ```
+3. Reload the shell:
+   ```bash
+   source ~/.bashrc
+   ```
+4. Verify installation:
+   ```bash
+   poetry --version
+   ```
+
+</details>

package/src/generators/preset/files/python/kong.json.template

@@ -0,0 +1,6 @@
+{
+  "id": "<%=id%>",
+  "name": "<%=name%>",
+  "sdk": "<%=platform%>",
+  "category": "unknown"
+}

package/src/generators/preset/files/python/project.json.template

@@ -0,0 +1,8 @@
+{
+  "name": "<%=name%>",
+  "$schema": "./node_modules/nx/schemas/project-schema.json",
+  "projectType": "application",
+  "sourceRoot": "./src",
+  "targets": {},
+  "tags": []
+}

package/src/generators/preset/files/python/pyproject.toml

@@ -0,0 +1,3 @@
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

package/src/generators/preset/files/python/requirements-dev.txt

@@ -0,0 +1,10 @@
+black==26.5.1
+flake8==7.3.0
+isort==8.0.1
+pylint==4.0.6
+pylint-pydantic==0.4.1
+pytest==9.1.1
+pytest-asyncio==1.4.0
+pytest-cov==7.1.0
+pytest-html==4.2.0
+pytest-sugar==1.1.1

package/src/generators/preset/files/python/requirements.txt

@@ -0,0 +1,5 @@
+pydantic==2.13.4
+kong-sdk==0.0.51
+<% if (variant === "with-s3") { -%>
+aiobotocore==2.15.2
+<% } -%>

package/src/generators/preset/files/python/src/frontend.py

@@ -0,0 +1,3 @@
+from kong.sdk.kong_frontend import KongFrontend, KongFrontendBuilder
+
+frontend: KongFrontend = KongFrontendBuilder().build()

package/src/generators/preset/files/python/src/input_data.py

@@ -0,0 +1,13 @@
+from pydantic import BaseModel, Field
+
+
+class InputData(BaseModel):
+    a: int = Field(
+        examples=[1],
+        description="An integer number",
+    )
+
+    b: int = Field(
+        examples=[2],
+        description="An integer number",
+    )

package/src/generators/preset/files/python/src/main.py

@@ -0,0 +1,28 @@
+import sys
+
+from kong.sdk.app import App
+from kong.sdk.kong_function import KongFunction
+from kong.sdk.kong_function_context import KongFunctionContext
+
+from frontend import frontend
+from input_data import InputData
+from output_data import OutputData
+
+
+class Main(KongFunction):
+    async def handle(self, data: InputData, context: KongFunctionContext) -> OutputData:
+        return OutputData(
+            sum_of=data.a + data.b,
+            comment=f"sum of {data.a} and {data.b}",
+        )
+
+
+app = App(
+    InputData,
+    OutputData,
+    Main,
+    frontend,
+)
+
+if __name__ == "__main__":
+    app.run(sys.argv)

package/src/generators/preset/files/python/src/main_test.py

@@ -0,0 +1,19 @@
+from kong.sdk.conftest import ExtensionFixture, extension_test_context
+
+from frontend import frontend
+from input_data import InputData
+from main import Main
+
+
+async def test_should_return_value_from_string_field_when_input_is_provided(
+    create_extension: ExtensionFixture,
+):
+    extension = create_extension(Main, InputData)
+
+    input_data = InputData(
+        a=1,
+        b=2,
+    )
+
+    output = await extension.handle(input_data, extension_test_context(frontend))
+    assert output.sum_of == 3

package/src/generators/preset/files/python/src/output_data.py

@@ -0,0 +1,15 @@
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class OutputData(BaseModel):
+    sum_of: int = Field(
+        examples=[3],
+        description="Result of a + b",
+    )
+
+    comment: Optional[str] = Field(
+        examples=["This example extension returns sum of a and b"],
+        description="A string field",
+    )

package/src/generators/preset/files/python-with-s3/src/frontend.py

@@ -0,0 +1,6 @@
+from kong.sdk.kong_frontend import KongFrontend, KongFrontendBuilder
+from kong.sdk.s3 import S3Secret
+
+frontend: KongFrontend = (
+    KongFrontendBuilder().with_secret_types("s3", {"s3": S3Secret}).with_form().build()
+)

package/src/generators/preset/files/python-with-s3/src/input_data.py

@@ -0,0 +1,17 @@
+from kong.sdk.kong_function_request import KongFunctionRequest
+from pydantic import BaseModel, Field
+
+
+class ExecuteData(BaseModel):
+    key: str = Field(
+        examples=["test/example.json"],
+        description="Key (path) of the object to download from the S3 bucket",
+    )
+
+
+class InputData(BaseModel):
+    request: KongFunctionRequest
+
+    execute: ExecuteData = Field(
+        description="Parameters for the 'execute' operation",
+    )

package/src/generators/preset/files/python-with-s3/src/main.py

@@ -0,0 +1,45 @@
+import sys
+from datetime import timedelta
+
+from kong.sdk.app import App
+from kong.sdk.kong_function import KongFunction
+from kong.sdk.kong_function_context import KongFunctionContext
+from kong.sdk.s3 import S3Secret
+
+from frontend import frontend
+from input_data import InputData
+from output_data import OutputData
+from s3 import create_s3_client
+
+
+class Main(KongFunction):
+    async def handle(self, data: InputData, context: KongFunctionContext) -> OutputData:
+        secret: S3Secret = context.secret.get("s3").data
+        client = await context.state.use(
+            key=f"{secret.endpoint}:{secret.port}:{secret.bucket}:{secret.accessKey}",
+            create=lambda: create_s3_client(secret),
+            unused=(timedelta(minutes=5), lambda c: c.close()),
+        )
+
+        response = await client.get_object(
+            Bucket=secret.bucket,
+            Key=data.execute.key,
+        )
+
+        body = await response["Body"].read()
+        print("body size:", len(body))
+
+        return OutputData(
+            key=data.execute.key,
+        )
+
+
+app = App(
+    InputData,
+    OutputData,
+    Main,
+    frontend,
+)
+
+if __name__ == "__main__":
+    app.run(sys.argv)

package/src/generators/preset/files/python-with-s3/src/main_test.py

@@ -0,0 +1,36 @@
+from frontend import frontend
+from input_data import ExecuteData, InputData
+from kong.sdk.conftest import ExtensionFixture, extension_test_context
+from kong.sdk.kong_function_request import KongFunctionRequest
+from kong.sdk.s3 import S3Secret
+from main import Main
+
+S3_SECRET = S3Secret(
+    accessKey="access",
+    secretKey="secret",
+    bucket="my-bucket",
+    region="us-east-1",
+    endpoint=None,
+    port=None,
+    useSSL=True,
+    pathStyle=False,
+)
+
+
+async def test_should_download_object_from_s3(
+    create_extension: ExtensionFixture,
+):
+    extension = create_extension(Main, InputData)
+
+    input_data = InputData(
+        request=KongFunctionRequest(operation="execute"),
+        execute=ExecuteData(key="test/example.json"),
+    )
+
+    context = extension_test_context(
+        frontend,
+        secrets={"s3": S3_SECRET},
+    )
+
+    output = await extension.handle(input_data, context)
+    assert output.key == "test/example.json"

package/src/generators/preset/files/python-with-s3/src/output_data.py

@@ -0,0 +1,8 @@
+from pydantic import BaseModel, Field
+
+
+class OutputData(BaseModel):
+    key: str = Field(
+        examples=["test/example.json"],
+        description="Key of the object that was downloaded",
+    )

package/src/generators/preset/files/python-with-s3/src/s3.py

@@ -0,0 +1,27 @@
+from aiobotocore.session import get_session
+from botocore.config import Config
+from kong.sdk.s3 import S3Secret
+
+
+async def create_s3_client(secret: S3Secret):
+    # Standard AWS endpoints are derived by boto from the region; only S3-compatible
+    # stores (MinIO, Ceph, ...) need an explicit endpoint override.
+    endpoint_url = None
+    if secret.endpoint and "amazonaws.com" not in secret.endpoint:
+        scheme = "https" if secret.useSSL else "http"
+        endpoint_url = (
+            f"{scheme}://{secret.endpoint}:{secret.port}"
+            if secret.port
+            else f"{scheme}://{secret.endpoint}"
+        )
+
+    client_context = get_session().create_client(
+        "s3",
+        region_name=secret.region,
+        endpoint_url=endpoint_url,
+        use_ssl=secret.useSSL,
+        aws_access_key_id=secret.accessKey,
+        aws_secret_access_key=secret.secretKey,
+        config=(Config(s3={"addressing_style": "path"}) if secret.pathStyle else None),
+    )
+    return await client_context.__aenter__()

package/src/generators/preset/files/python-with-secret/src/frontend.py

@@ -0,0 +1,17 @@
+from kong.sdk.kong_frontend import KongFrontend, KongFrontendBuilder
+from pydantic import BaseModel, Field
+
+
+class MySecret(BaseModel):
+    my_key: str = Field(
+        examples=["example-0123456789"],
+        description="An example of secret field",
+    )
+
+
+frontend: KongFrontend = (
+    KongFrontendBuilder()
+    .with_secret_types("primary", {"<%=name%>-secret": MySecret})
+    .with_form()
+    .build()
+)

package/src/generators/preset/files/python-with-secret/src/input_data.py

@@ -0,0 +1,40 @@
+from typing import Optional
+
+from kong.sdk.kong_function_request import KongFunctionRequest
+from pydantic import BaseModel, Field
+
+
+class OperationData(BaseModel):
+    a: int = Field(
+        examples=[1],
+        description="An integer number",
+    )
+
+    b: int = Field(
+        examples=[2],
+        description="An integer number",
+    )
+
+
+class InputData(BaseModel):
+    request: KongFunctionRequest
+
+    sum: Optional[OperationData] = Field(
+        default=None,
+        description="Operands for the 'sum' operation",
+    )
+
+    sub: Optional[OperationData] = Field(
+        default=None,
+        description="Operands for the 'sub' operation",
+    )
+
+    multiply: Optional[OperationData] = Field(
+        default=None,
+        description="Operands for the 'multiply' operation",
+    )
+
+    divide: Optional[OperationData] = Field(
+        default=None,
+        description="Operands for the 'divide' operation",
+    )

package/src/generators/preset/files/python-with-secret/src/main.py

@@ -0,0 +1,51 @@
+import sys
+
+from frontend import frontend
+from input_data import InputData, OperationData
+from kong.sdk.app import App
+from kong.sdk.kong_function import KongFunction
+from kong.sdk.kong_function_context import KongFunctionContext
+from output_data import OutputData
+
+
+class Main(KongFunction):
+    async def handle(self, data: InputData, context: KongFunctionContext) -> OutputData:
+        operation = data.request.operation
+        operands = getattr(data, operation, None)
+        if not isinstance(operands, OperationData):
+            raise ValueError(f"Missing or unsupported operation '{operation}'")
+
+        if operation == "sum":
+            result = operands.a + operands.b
+        elif operation == "sub":
+            result = operands.a - operands.b
+        elif operation == "multiply":
+            result = operands.a * operands.b
+        elif operation == "divide":
+            if operands.b == 0:
+                raise ValueError("Cannot divide by zero")
+            result = operands.a // operands.b
+        else:
+            raise ValueError(f"Unsupported operation '{operation}'")
+
+        comment = f"{operation} result is {result}"
+
+        secret = context.secret.find("primary")
+        if secret is not None:
+            comment += " (authenticated)"
+
+        return OutputData(
+            result=result,
+            comment=comment,
+        )
+
+
+app = App(
+    InputData,
+    OutputData,
+    Main,
+    frontend,
+)
+
+if __name__ == "__main__":
+    app.run(sys.argv)

package/src/generators/preset/files/python-with-secret/src/main_test.py

@@ -0,0 +1,39 @@
+from frontend import MySecret, frontend
+from input_data import InputData, OperationData
+from kong.sdk.conftest import ExtensionFixture, extension_test_context
+from kong.sdk.kong_function_request import KongFunctionRequest
+from main import Main
+
+
+async def test_should_add_operands_when_operation_is_sum(
+    create_extension: ExtensionFixture,
+):
+    extension = create_extension(Main, InputData)
+
+    input_data = InputData(
+        request=KongFunctionRequest(operation="sum"),
+        sum=OperationData(a=1, b=2),
+    )
+
+    output = await extension.handle(input_data, extension_test_context(frontend))
+    assert output.result == 3
+
+
+async def test_should_note_authentication_when_secret_is_provided(
+    create_extension: ExtensionFixture,
+):
+    extension = create_extension(Main, InputData)
+
+    input_data = InputData(
+        request=KongFunctionRequest(operation="sum"),
+        sum=OperationData(a=1, b=2),
+    )
+
+    context = extension_test_context(
+        frontend,
+        {"primary": MySecret(my_key="example-0123456789")},
+    )
+    output = await extension.handle(input_data, context)
+
+    assert output.result == 3
+    assert output.comment == "sum result is 3 (authenticated)"