-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
56eb1e7
commit 7134280
Showing
7 changed files
with
874 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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... |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
Oops, something went wrong.