Merge pull request #7 from northpowered/6-separate-documentation

Docs first version

.github/workflows/documentation-deployment.yml

@@ -0,0 +1,16 @@
+name: Documentation deployment
+
+on:
+  push:
+    branches:
+      - main
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v3
+        with:
+          python-version: 3.x
+      - run: pip install mkdocs-material
+      - run: mkdocs gh-deploy --force

docs/how-it-works.md

@@ -0,0 +1,56 @@
+# How it works?
+
+## Principal
+
+App is a combination of FastAPI-based REST server and official Temporal SDK in async runtime. Executor is stateless and create every new connection to Temporal server with every REST invocation.
+
+## Activity
+
+### Execution
+
+To execute any remote activity, the app uses **INTERNAL_WORKFLOW**, which consists of **execute_activity** method.
+
+This internal workflow executes in [TEMPORAL_INTERNAL_TASK_QUEUE](./index.md#temporal_internal_task_queue) and can be renamed (see [TEMPORAL_INTERNAL_FLOW_NAME](./index.md#temporal_internal_flow_name))
+
+All attributes, started with **parent_workflow_** are the attributes for this workflow, for ex:
+
+```
+parent_workflow_id
+parent_workflow_execution_timeout
+parent_workflow_run_timeout
+parent_workflow_task_timeout
+```
+They are similar to Temporal SDK attributes for workflows, see the official API documentaion
+
+Other attributes are using for **execute_activity** themselves, for ex:
+
+```
+activity_name
+activity_task_queue
+args
+start_to_close_timeout
+schedule_to_start_timeout
+heartbeat_timeout
+schedule_to_close_timeout
+retry_policy
+```
+
+## Workflow
+
+### Execution
+
+Remote workflow execution is much simple, then the activity one. It uses **client.execute_workflow** method of official SDK.
+
+There are some args for this method:
+
+```
+workflow_name
+workflow_task_queue
+args
+workflow_id
+execution_timeout
+```
+
+### Execution as a child workflow
+
+Feature will be added soon...

docs/index.md

@@ -0,0 +1,117 @@
+# Getting started
+
+[![codecov](https://codecov.io/github/northpowered/temporal-rest-executor/branch/main/graph/badge.svg?token=0Ei4nXXFfL)](https://codecov.io/github/northpowered/temporal-rest-executor)
+[![CI](https://github.com/northpowered/temporal-rest-executor/actions/workflows/ci.yml/badge.svg)](https://github.com/northpowered/temporal-rest-executor/actions/workflows/ci.yml)
+[![Docker Image CD](https://github.com/northpowered/temporal-rest-executor/actions/workflows/docker-image.yml/badge.svg)](https://github.com/northpowered/temporal-rest-executor/actions/workflows/docker-image.yml)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=northpowered_temporal-rest-executor&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=northpowered_temporal-rest-executor)
+
+
+## What is it?
+
+This is a simple tool to operate with [Temporal](https://temporal.io/) workflows/activities through the REST endpoints.
+
+Service provides some REST endpoints which can execute (now) any workflow or activity, registered is the namespace.
+
+Based on [FastAPI](https://github.com/tiangolo/fastapi) and may be useful for development and QA.
+
+## Quick start
+
+### Docker
+
+Run the docker image
+```bash
+docker run -p 8000:8000 ghcr.io/northpowered/temporal-rest-executor:latest
+```
+
+You can add Temporal endpoint as an env var. All env vars`ll be listed below.
+
+```bash
+docker run -e TEMPORAL_ENDPOINT=temporal:7233 -p 8000:8000 ghcr.io/northpowered/temporal-rest-executor:latest
+```
+
+And specify docker network (this is the example for [default Temporal docker-compose manifest](https://github.com/temporalio/docker-compose/blob/main/docker-compose.yml))
+```bash
+docker run -e TEMPORAL_ENDPOINT=temporal:7233 -p 8000:8000 --network temporal-network ghcr.io/northpowered/temporal-rest-executor:latest
+```
+
+### Manual start
+
+Use it for development or debugging
+
+```bash
+git clone git@github.com:northpowered/temporal-rest-executor.git
+
+poetry install
+
+python3 src/run.py
+```
+
+## Configuration
+
+### TEMPORAL_ENDPOINT
+
+Temporal endpoint string
+
+`TEMPORAL_ENDPOINT=localhost:7233`
+
+### TEMPORAL_NAMESPACE
+
+Temporal namespace string
+
+Will be deprecated soon, moved to the REST args
+
+`TEMPORAL_NAMESPACE=default`
+
+### TEMPORAL_INTERNAL_FLOW_NAME
+
+Name of the workflow for execution remote activities
+
+`TEMPORAL_INTERNAL_FLOW_NAME=InternalExecutionWorkflow`
+
+### TEMPORAL_INTERNAL_TASK_QUEUE
+
+Task queue for internal workflow
+
+`TEMPORAL_INTERNAL_TASK_QUEUE=internal-execution-queue`
+
+### UVICORN_BIND_ADDR
+
+Address for uvicorn HTTP server
+
+`UVICORN_BIND_ADDR=0.0.0.0`
+
+### UVICORN_BIND_PORT
+
+Port for uvicorn HTTP server
+
+`UVICORN_BIND_PORT=8000`
+
+### TELEMETRY_ENABLED
+
+Flag to enable OTEL collection
+
+`TELEMETRY_ENABLED=True`
+
+### TELEMETRY_AGENT_HOST
+
+OTEL collector address
+
+`TELEMETRY_AGENT_HOST=localhost`
+
+### TELEMETRY_AGENT_PORT
+
+OTEL collector port
+
+`TELEMETRY_AGENT_PORT=6831`
+
+### PROMETHEUS_ENDPOINT_ENABLED
+
+Flag to enable Prometheus endpoint
+
+`PROMETHEUS_ENDPOINT_ENABLED=True`
+
+### PROMETHEUS_ENDPOINT_PORT
+
+Prometheus endpoint port to bind on
+
+`PROMETHEUS_ENDPOINT_PORT=9000`

docs/usage.md

@@ -0,0 +1,123 @@
+# Usage
+
+## Activity execution
+
+URL is `/v1/activity/execute`
+
+CURL example:
+
+```bash
+curl -X 'POST' \
+  'http://localhost:8000/v1/activity/execute' \
+  -H 'accept: application/json' \
+  -H 'Content-Type: application/json' \
+  -d '{
+  "activity_name": "your_remote_activity",
+  "activity_task_queue": "your_queue",
+  "args": "some args: string, object or null",
+  "start_to_close_timeout": 10,
+  "parent_workflow_id": "MyId",
+  "schedule_to_start_timeout": 0,
+  "heartbeat_timeout": 0,
+  "schedule_to_close_timeout": 0,
+  "retry_policy": {
+    "initial_interval": 1,
+    "backoff_coefficient": 2,
+    "maximum_interval": 0,
+    "maximum_attempts": 0
+  },
+  "parent_workflow_execution_timeout": 10,
+  "parent_workflow_run_timeout": 0,
+  "parent_workflow_task_timeout": 0
+}'
+```
+
+### activity_name
+
+**REQUIRED** name of remote activity
+
+### activity_task_queue
+
+**REQUIRED** name of queue with remote activity
+
+### args
+
+Default to *null*
+
+#### Any
+
+You can use any available argument format:
+
+`"args": "string"`
+
+`"args": 100500`
+
+`"args": true`
+
+`"args": "[1,2,3]"`
+
+`"args": "{'foo':'bar'}"`
+
+#### null
+
+Using null by default obliges app use overloaded **execute_activity** method with NO args. So, now you can`t translate *null* (*None*) as an arg to remote activity. Will be fixed soon.
+
+### Retry policy
+
+Default to *null*, but you can provide it as an object in format like:
+```json
+"retry_policy": {
+    "initial_interval": 1, # REQUIRED
+    "backoff_coefficient": 2, # REQUIRED
+    "maximum_interval": null,
+    "maximum_attempts": 0
+}
+```
+
+### Other arguments
+
+All other arguments in example above are similar to Temporal API
+
+---
+
+## Workflow execution
+
+URL is `/v1/workflow/execute`
+
+CURL example:
+
+```bash
+curl -X 'POST' \
+  'http://localhost:8000/v1/workflow/execute' \
+  -H 'accept: application/json' \
+  -H 'Content-Type: application/json' \
+  -d '{
+  "workflow_name": "string",
+  "workflow_task_queue": "string",
+  "args": "string",
+  "workflow_id": "string",
+  "execution_timeout": 1
+}'
+```
+
+### workflow_name
+
+**REQUIRED** name of remote workflow
+
+### workflow_task_queue
+
+**REQUIRED** name of queue with remote workflow
+
+### args
+
+Args mechanic is similar to [activity](#args) one
+
+### workflow_id
+
+Default to *null*
+
+If workflow_id is not provided or *null*, **UUID4** will be used
+
+### execution_timeout
+
+Default to *10* (seconds)

mkdocs.yml

@@ -0,0 +1,27 @@
+site_name: Temporal-REST-executor
+site_description: Small REST with Swagger UI server to work with Temporal objects 
+repo_url: https://github.com/northpowered/temporal-rest-executor
+repo_name: northpowered/temporal-rest-executor
+
+theme:
+  name: material
+  language: en
+  features:
+  - navigation.tracking
+  - content.code.copy
+
+plugins:
+  - tags
+
+markdown_extensions:
+  - tables
+  - pymdownx.emoji:
+      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences