py-serverless-kit 0.1.3__tar.gz → 0.3.0__tar.gz

{py_serverless_kit-0.1.3 → py_serverless_kit-0.3.0}/CHANGELOG.md

@@ -6,6 +6,25 @@ All notable changes to this project are documented here. The format follows [Kee
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-17
+
+### Added
+- On-premises deploy targets. `provider.options.deploy.method` is `local` (default, previous behaviour), `ssh` (copy the host over OpenSSH and start a process or systemd unit), or `docker` (build an image that already contains Python). When the server has no Python, set `python: bundle` to ship a portable CPython, or use `method: docker`. `python_home` / `python_url` cover air-gapped mirrors. Wheels are vendored for the target OS/arch (manylinux when the server is Linux).
+- Example [17-on-premises-remote](examples/17-on-premises-remote): SSH + bundled interpreter + systemd.
+
+### Fixed
+- On-prem host: Windows process helpers (`ctypes.windll`, `subprocess.DETACHED_PROCESS`) are gated on `sys.platform == "win32"` so mypy on Linux/macOS CI no longer reports missing attributes.
+
+Redeploy on-premises hosts to pick up the new `onprem_deploy.py` provisioner. Handler code is unchanged.
+
+## [0.2.0] - 2026-10-17
+
+### Added
+- On-premises provider (`provider.name: onprem`). `pskit deploy` starts one long-lived Python process on the machine that runs the command. HTTP is served directly. Schedules, file queues (with dead-letter and partial batch failure), directory storage and file topics are created at start when they do not already exist. Point `provider.options.services.<kind>` at `{use: directory, path: ...}` to use a directory you already have. `existing: true` waits for that directory instead of creating it. Workflows run on the embedded engine inside the host, and `invoke()` stays in-process. `pskit remove` stops the process and leaves the data directory in place.
+- Example [16-on-premises](examples/16-on-premises). Every other example has an `providers.onprem` block (its own port, public auth where a cloud authorizer does not apply, local state where the file used a cloud backend).
+
+No change to handlers that already run on a cloud. Redeploy to pick up the new runtime if you use `BatchResult` or `invoke()` on premises.
+
 ## [0.1.3] - 2026-10-15
 
 ### Fixed

{py_serverless_kit-0.1.3 → py_serverless_kit-0.3.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: py-serverless-kit
-Version: 0.1.3
-Summary: Write a Python serverless function once and deploy it to AWS, Azure, GCP and 7 more clouds with one YAML file, powered by Terraform.
+Version: 0.3.0
+Summary: Write a Python serverless function once and deploy it to AWS, Azure, GCP, 7 more clouds, or an on-premises host with one YAML file, powered by Terraform.
 Project-URL: Homepage, https://github.com/ak9347128658/serverless_kit
 Project-URL: Documentation, https://github.com/ak9347128658/serverless_kit/tree/main/docs
 Project-URL: Issues, https://github.com/ak9347128658/serverless_kit/issues
@@ -10,7 +10,7 @@ Author: Asif Khan @ Kavion.ai
 Maintainer: Asif Khan @ Kavion.ai
 License: MIT
 License-File: LICENSE
-Keywords: aws,azure,faas,gcp,lambda,multi-cloud,serverless,step-functions,terraform
+Keywords: aws,azure,faas,gcp,lambda,multi-cloud,on-premises,serverless,step-functions,terraform
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -48,12 +48,12 @@ Description-Content-Type: text/markdown
 [![PyPI](https://img.shields.io/pypi/v/py-serverless-kit.svg)](https://pypi.org/project/py-serverless-kit/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/ak9347128658/serverless_kit/blob/main/LICENSE)
 
-**Write your Python functions once. Deploy them to any of 10 clouds by changing one line of YAML.**
+**Write your Python functions once. Deploy them to any of 10 clouds, or to your own machine, by changing one line of YAML.**
 
 `py-serverless-kit` (CLI: `pskit`) is a Serverless-Framework-style toolkit built on **Terraform**. Your handlers use one small, provider-neutral API (`Event`, `Context`, `Response`). A `pskit.yml` file says which cloud they run on and what triggers them: HTTP, schedules, queues, storage, topics. The same file can also define workflows in the style of Step Functions. `pskit deploy` generates Terraform for the chosen cloud, applies it, and builds an HTML dashboard of everything you deployed.
 
 ```python
-# app/handlers.py - identical on AWS, Azure, GCP, Alibaba, Oracle, IBM, DigitalOcean, Tencent, Huawei, Cloudflare
+# app/handlers.py - identical on AWS, Azure, GCP, Alibaba, Oracle, IBM, DigitalOcean, Tencent, Huawei, Cloudflare, and on premises
 from py_serverless_kit import Event, Context, NotFound
 
 def get_order(event: Event, ctx: Context):
@@ -67,7 +67,7 @@ def get_order(event: Event, ctx: Context):
 # pskit.yml
 service: orders
 provider:
-  name: aws          # <- change to gcp, azure, alibaba, ... and redeploy. That's the migration.
+  name: aws          # <- change to gcp, azure, onprem, ... and redeploy. That's the migration.
   region: us-east-1
 functions:
   get-order:
@@ -97,7 +97,7 @@ Teams that build on AWS Lambda and Step Functions end up with code full of API G
 
 ## Features
 
-- **10 providers:** AWS Lambda, Azure Functions, Google Cloud Functions (gen2), Alibaba Function Compute, Oracle Functions, IBM Code Engine, DigitalOcean Functions, Tencent SCF, Huawei FunctionGraph, Cloudflare Workers.
+- **10 clouds and an on-premises host:** AWS Lambda, Azure Functions, Google Cloud Functions (gen2), Alibaba Function Compute, Oracle Functions, IBM Code Engine, DigitalOcean Functions, Tencent SCF, Huawei FunctionGraph, Cloudflare Workers, plus a process on your own machine or a remote server (`onprem`: local, SSH, Docker, or a bundled CPython when the server has no Python).
 - **Triggers:** HTTP (path params, CORS, auth), schedules (rate/cron, translated into each cloud's cron dialect), queues, object storage, pub/sub topics, and direct function-to-function `invoke()`.
 - **Workflows:** task / choice / wait / pass / parallel / map / succeed / fail with retry and catch. Native on AWS and GCP; an embedded engine on the other clouds; runnable locally with `pskit workflow run`.
 - **Terraform underneath:** real, reviewable `main.tf.json`, any backend (S3, GCS, azurerm, ...), works with OpenTofu. Escape hatches: `terraform.extra`, `${tf:...}` references, per-function `options`.
@@ -120,6 +120,7 @@ Teams that build on AWS Lambda and Step Functions end up with code full of API G
 | IBM Code Engine | beta | ✅ | – | – | – | – | embedded |
 | Oracle Cloud Functions | experimental | ✅ | – | – | ✅ | – | embedded |
 | Cloudflare Workers (Python) | experimental | ✅ | ✅ | – | – | – | embedded |
+| On-premises | experimental | ✅ | ✅ | ✅ files | ✅ directory | ✅ files | embedded (local, SSH, or Docker) |
 
 Run `pskit providers` for the live matrix. If a config uses a trigger the target cloud can't support, **`pskit validate` fails with a clear message instead of deploying something half-working.**
 
@@ -251,7 +252,7 @@ More: [docs/architecture.md](https://github.com/ak9347128658/serverless_kit/blob
 
 ## Examples
 
-Fifteen runnable scenarios live in [`examples/`](https://github.com/ak9347128658/serverless_kit/tree/main/examples/). They are tested in CI.
+Sixteen runnable scenarios live in [`examples/`](https://github.com/ak9347128658/serverless_kit/tree/main/examples/). They are tested in CI.
 
 | | |
 |---|---|
@@ -262,7 +263,8 @@ Fifteen runnable scenarios live in [`examples/`](https://github.com/ak9347128658
 | [05-storage-events](https://github.com/ak9347128658/serverless_kit/tree/main/examples/05-storage-events) | Object created/deleted with filters |
 | [06-pubsub-topic](https://github.com/ak9347128658/serverless_kit/tree/main/examples/06-pubsub-topic) | Topic fan-out and filters |
 | [07-workflow-orders](https://github.com/ak9347128658/serverless_kit/tree/main/examples/07-workflow-orders) | Every workflow state type, retry/catch |
-| [08-multi-cloud](https://github.com/ak9347128658/serverless_kit/tree/main/examples/08-multi-cloud) | Same code, all 10 providers |
+| [08-multi-cloud](https://github.com/ak9347128658/serverless_kit/tree/main/examples/08-multi-cloud) | Same code, all 11 providers |
+| [16-on-premises](https://github.com/ak9347128658/serverless_kit/tree/main/examples/16-on-premises) | HTTP, schedule, queue, storage, topic and a workflow on one machine |
 | [09-function-invoke](https://github.com/ak9347128658/serverless_kit/tree/main/examples/09-function-invoke) | Function-to-function `invoke()` |
 | [10-stages-and-config](https://github.com/ak9347128658/serverless_kit/tree/main/examples/10-stages-and-config) | Stages, variables, secrets |
 | [11-custom-terraform](https://github.com/ak9347128658/serverless_kit/tree/main/examples/11-custom-terraform) | `terraform.extra`, `${tf:...}`, remote state, hooks |

{py_serverless_kit-0.1.3 → py_serverless_kit-0.3.0}/README.md

@@ -4,12 +4,12 @@
 [![PyPI](https://img.shields.io/pypi/v/py-serverless-kit.svg)](https://pypi.org/project/py-serverless-kit/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/ak9347128658/serverless_kit/blob/main/LICENSE)
 
-**Write your Python functions once. Deploy them to any of 10 clouds by changing one line of YAML.**
+**Write your Python functions once. Deploy them to any of 10 clouds, or to your own machine, by changing one line of YAML.**
 
 `py-serverless-kit` (CLI: `pskit`) is a Serverless-Framework-style toolkit built on **Terraform**. Your handlers use one small, provider-neutral API (`Event`, `Context`, `Response`). A `pskit.yml` file says which cloud they run on and what triggers them: HTTP, schedules, queues, storage, topics. The same file can also define workflows in the style of Step Functions. `pskit deploy` generates Terraform for the chosen cloud, applies it, and builds an HTML dashboard of everything you deployed.
 
 ```python
-# app/handlers.py - identical on AWS, Azure, GCP, Alibaba, Oracle, IBM, DigitalOcean, Tencent, Huawei, Cloudflare
+# app/handlers.py - identical on AWS, Azure, GCP, Alibaba, Oracle, IBM, DigitalOcean, Tencent, Huawei, Cloudflare, and on premises
 from py_serverless_kit import Event, Context, NotFound
 
 def get_order(event: Event, ctx: Context):
@@ -23,7 +23,7 @@ def get_order(event: Event, ctx: Context):
 # pskit.yml
 service: orders
 provider:
-  name: aws          # <- change to gcp, azure, alibaba, ... and redeploy. That's the migration.
+  name: aws          # <- change to gcp, azure, onprem, ... and redeploy. That's the migration.
   region: us-east-1
 functions:
   get-order:
@@ -53,7 +53,7 @@ Teams that build on AWS Lambda and Step Functions end up with code full of API G
 
 ## Features
 
-- **10 providers:** AWS Lambda, Azure Functions, Google Cloud Functions (gen2), Alibaba Function Compute, Oracle Functions, IBM Code Engine, DigitalOcean Functions, Tencent SCF, Huawei FunctionGraph, Cloudflare Workers.
+- **10 clouds and an on-premises host:** AWS Lambda, Azure Functions, Google Cloud Functions (gen2), Alibaba Function Compute, Oracle Functions, IBM Code Engine, DigitalOcean Functions, Tencent SCF, Huawei FunctionGraph, Cloudflare Workers, plus a process on your own machine or a remote server (`onprem`: local, SSH, Docker, or a bundled CPython when the server has no Python).
 - **Triggers:** HTTP (path params, CORS, auth), schedules (rate/cron, translated into each cloud's cron dialect), queues, object storage, pub/sub topics, and direct function-to-function `invoke()`.
 - **Workflows:** task / choice / wait / pass / parallel / map / succeed / fail with retry and catch. Native on AWS and GCP; an embedded engine on the other clouds; runnable locally with `pskit workflow run`.
 - **Terraform underneath:** real, reviewable `main.tf.json`, any backend (S3, GCS, azurerm, ...), works with OpenTofu. Escape hatches: `terraform.extra`, `${tf:...}` references, per-function `options`.
@@ -76,6 +76,7 @@ Teams that build on AWS Lambda and Step Functions end up with code full of API G
 | IBM Code Engine | beta | ✅ | – | – | – | – | embedded |
 | Oracle Cloud Functions | experimental | ✅ | – | – | ✅ | – | embedded |
 | Cloudflare Workers (Python) | experimental | ✅ | ✅ | – | – | – | embedded |
+| On-premises | experimental | ✅ | ✅ | ✅ files | ✅ directory | ✅ files | embedded (local, SSH, or Docker) |
 
 Run `pskit providers` for the live matrix. If a config uses a trigger the target cloud can't support, **`pskit validate` fails with a clear message instead of deploying something half-working.**
 
@@ -207,7 +208,7 @@ More: [docs/architecture.md](https://github.com/ak9347128658/serverless_kit/blob
 
 ## Examples
 
-Fifteen runnable scenarios live in [`examples/`](https://github.com/ak9347128658/serverless_kit/tree/main/examples/). They are tested in CI.
+Sixteen runnable scenarios live in [`examples/`](https://github.com/ak9347128658/serverless_kit/tree/main/examples/). They are tested in CI.
 
 | | |
 |---|---|
@@ -218,7 +219,8 @@ Fifteen runnable scenarios live in [`examples/`](https://github.com/ak9347128658
 | [05-storage-events](https://github.com/ak9347128658/serverless_kit/tree/main/examples/05-storage-events) | Object created/deleted with filters |
 | [06-pubsub-topic](https://github.com/ak9347128658/serverless_kit/tree/main/examples/06-pubsub-topic) | Topic fan-out and filters |
 | [07-workflow-orders](https://github.com/ak9347128658/serverless_kit/tree/main/examples/07-workflow-orders) | Every workflow state type, retry/catch |
-| [08-multi-cloud](https://github.com/ak9347128658/serverless_kit/tree/main/examples/08-multi-cloud) | Same code, all 10 providers |
+| [08-multi-cloud](https://github.com/ak9347128658/serverless_kit/tree/main/examples/08-multi-cloud) | Same code, all 11 providers |
+| [16-on-premises](https://github.com/ak9347128658/serverless_kit/tree/main/examples/16-on-premises) | HTTP, schedule, queue, storage, topic and a workflow on one machine |
 | [09-function-invoke](https://github.com/ak9347128658/serverless_kit/tree/main/examples/09-function-invoke) | Function-to-function `invoke()` |
 | [10-stages-and-config](https://github.com/ak9347128658/serverless_kit/tree/main/examples/10-stages-and-config) | Stages, variables, secrets |
 | [11-custom-terraform](https://github.com/ak9347128658/serverless_kit/tree/main/examples/11-custom-terraform) | `terraform.extra`, `${tf:...}`, remote state, hooks |

{py_serverless_kit-0.1.3 → py_serverless_kit-0.3.0}/docs/README.md

@@ -1,6 +1,6 @@
 # py-serverless-kit documentation
 
-Write a Python function once, describe its triggers in `pskit.yml`, and deploy it to any of 10 clouds with Terraform. Moving to another cloud means changing `provider.name`. The handler code stays the same.
+Write a Python function once, describe its triggers in `pskit.yml`, and deploy it to any of 10 clouds or to an on-premises host with Terraform. Moving to another target means changing `provider.name`. The handler code stays the same.
 
 | Page | What it covers |
 |---|---|

{py_serverless_kit-0.1.3 → py_serverless_kit-0.3.0}/docs/architecture.md

@@ -45,9 +45,12 @@ artifact.zip
 ├── <shim>                        pskit_entry.py (aws) · main.py (gcp) · function_app.py + host.json (azure)
 │                                 index.py (alibaba/tencent/huawei) · __main__.py (ibm/do)
 │                                 func.py + func.yaml + Dockerfile (oracle) · generated worker module (cloudflare)
+│                                 onprem_handler.py (onprem; the host is started beside the zip)
 └── dependencies or requirements.txt
 ```
 
+On-premises also writes `.pskit/onprem-<stage>/onprem_app/` (`pskit_host.json`, `onprem_ctl.py`, `onprem_deploy.py`, the staged bundle, and a Dockerfile or systemd unit when those methods are selected). Terraform `local-exec` runs `onprem_deploy.py apply`, which starts the host on this machine, copies it over SSH (detached process or systemd, optional portable CPython), or builds a Docker image.
+
 ## Runtime flow
 
 ```

{py_serverless_kit-0.1.3 → py_serverless_kit-0.3.0}/docs/cli.md

@@ -13,7 +13,7 @@ Every command that loads a project accepts:
 | Flag | Meaning |
 |---|---|
 | `-c, --config FILE` | config file (default: `pskit.yml`, `pskit.yaml`, `serverless_kit.yml`, `serverless_kit.yaml`) |
-| `-p, --provider NAME` | override `provider.name` (`aws`, `azure`, `gcp`, `alibaba`, `oracle`, `ibm`, `digitalocean`, `tencent`, `huawei`, `cloudflare`) |
+| `-p, --provider NAME` | override `provider.name` (`aws`, `azure`, `gcp`, `alibaba`, `oracle`, `ibm`, `digitalocean`, `tencent`, `huawei`, `cloudflare`, `onprem`) |
 | `-s, --stage NAME` | stage, e.g. `dev`, `staging`, `prod` |
 | `-r, --region NAME` | override `provider.region` |
 | `-v, --verbose` | print tracebacks on errors |

{py_serverless_kit-0.1.3 → py_serverless_kit-0.3.0}/docs/configuration.md

@@ -33,7 +33,7 @@ extends: base.yml               # inherit another file (see below)
 
 | Key | Type | Default | Notes |
 |---|---|---|---|
-| `name` | `aws` \| `azure` \| `gcp` \| `alibaba` \| `oracle` \| `ibm` \| `digitalocean` \| `tencent` \| `huawei` \| `cloudflare` | — | required (or `--provider`) |
+| `name` | `aws` \| `azure` \| `gcp` \| `alibaba` \| `oracle` \| `ibm` \| `digitalocean` \| `tencent` \| `huawei` \| `cloudflare` \| `onprem` | — | required (or `--provider`) |
 | `region` | string | provider default | e.g. `us-east-1`, `europe-west1`, `eastus` |
 | `stage` | string | `dev` | `[a-z][a-z0-9-]{0,15}`; overridden by `--stage` |
 | `runtime` | `python3.9` … `python3.14` | see [default runtime](#default-runtime) | provider support varies |
@@ -45,7 +45,7 @@ extends: base.yml               # inherit another file (see below)
 | `iam.statements` | list of `{effect, actions, resources}` | `[]` | AWS-style; `effect` defaults to `Allow`, `resources` to `["*"]`. Ignored (with a warning) on clouds that don't map it |
 | `iam.role` | string | — | use an existing role / agency instead of creating one |
 | `log_retention_days` | int or null | `14` | AWS CloudWatch log group retention |
-| `options` | mapping | `{}` | provider-specific settings, see [providers.md](providers.md) |
+| `options` | mapping | `{}` | provider-specific settings, see [providers.md](providers.md). On-premises: `deploy.method` is `local`, `ssh`, or `docker`; `python: bundle` ships an interpreter when the server has none |
 | `state` | mapping | local state | see [state](#state-remote-terraform-backend) |
 | `terraform` | mapping | | see [terraform](#terraform) |
 
@@ -189,7 +189,8 @@ Relative paths resolve from the extending file. Circular `extends` is an error.
 
    So a child file's explicit values beat its parent's per-provider overrides.
 2. `stages.<active stage>` (merged across all files; the child wins).
-3. CLI flags: `--provider`, `--stage`, `--region`.
+3. `stages.<active stage>.providers.<active provider>`, when that stage must differ for one target (for example a cloud state backend on `prod` and local state for `onprem`).
+4. CLI flags: `--provider`, `--stage`, `--region`.
 
 Dicts are deep-merged; lists are replaced, not appended.
 

{py_serverless_kit-0.1.3 → py_serverless_kit-0.3.0}/docs/events.md

@@ -18,13 +18,13 @@ A function with no events is *invoke-only*: it can be called by workflows, by `i
 
 Support at a glance (the full detail is below and in [providers.md](providers.md)):
 
-| Trigger | aws | gcp | azure | alibaba | oracle | ibm | digitalocean | tencent | huawei | cloudflare |
-|---|---|---|---|---|---|---|---|---|---|---|
-| `http` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓¹ | ✓ |
-| `schedule` | ✓ | ✓ | ✓ | ✓ | – | – | ✓ | ✓ | ✓ | ✓ |
-| `queue` | ✓ SQS | ✓ Pub/Sub | ✓ Storage Queue | – | – | – | – | – | – | – |
-| `storage` | ✓ S3 | ✓ GCS | ✓ Blob (created only) | ✓ OSS | ✓ Object Storage | – | – | ✓ COS | ✓ OBS | – |
-| `topic` | ✓ SNS | ✓ Pub/Sub | ✓ Service Bus | ✓ MNS | – | – | – | – | ✓ SMN | – |
+| Trigger | aws | gcp | azure | alibaba | oracle | ibm | digitalocean | tencent | huawei | cloudflare | onprem |
+|---|---|---|---|---|---|---|---|---|---|---|---|
+| `http` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓¹ | ✓ | ✓ |
+| `schedule` | ✓ | ✓ | ✓ | ✓ | – | – | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `queue` | ✓ SQS | ✓ Pub/Sub | ✓ Storage Queue | – | – | – | – | – | – | – | ✓ files |
+| `storage` | ✓ S3 | ✓ GCS | ✓ Blob (created only) | ✓ OSS | ✓ Object Storage | – | – | ✓ COS | ✓ OBS | – | ✓ directory |
+| `topic` | ✓ SNS | ✓ Pub/Sub | ✓ Service Bus | ✓ MNS | – | – | – | – | ✓ SMN | – | ✓ files |
 
 ¹ Huawei HTTP needs `provider.options.apig_instance_id`.
 
@@ -110,6 +110,7 @@ pskit converts the portable syntax to each cloud's dialect:
 | huawei | timer trigger | `Rate` (`5m`) or 6-field cron with `?` |
 | digitalocean | `project.yml` scheduler trigger | 5-field cron |
 | cloudflare | Cron Triggers | 5-field cron |
+| onprem | in-process scheduler | rate in seconds, or 5-field cron. A rate such as `7 minutes` is valid here |
 
 A rate that can't be expressed as cron on cron-only clouds (e.g. `7 minutes`) fails validation; use a divisor of 60 minutes or 24 hours. `timezone` is honoured by AWS, GCP and Alibaba (cron form); Azure ignores it with a warning.
 
@@ -139,6 +140,8 @@ The handler gets `event.type == "queue"` and `event.records`, one `Record` per m
 | `fifo` | ✓ (`.fifo` suffix, content-based dedup) | ignored (warning) | ignored (warning) |
 | partial batch failure | ✓ `batchItemFailures` | whole delivery retried | whole delivery retried |
 
+On premises the same options are implemented by a file broker (`batch_size`, `batch_window`, visibility, dead-letter, `max_receive`, `fifo`). `BatchResult` retries only the failed message ids, as on AWS. Set `provider.options.services.queue` to `builtin` (created at start) or `{use: directory, path: ...}`. `existing: true` waits for that directory. Example: [`examples/04-queue-worker`](../examples/04-queue-worker) and [`examples/16-on-premises`](../examples/16-on-premises).
+
 On GCP a "queue" is a Pub/Sub topic with a push trigger, because GCP has no SQS-style pull trigger. Azure queue names must be 3–63 lowercase letters, digits and dashes. Example: [`examples/04-queue-worker`](../examples/04-queue-worker).
 
 ---
@@ -166,6 +169,7 @@ Each record has `bucket`, `key`, `size` and `action` (`"created"` / `"deleted"`)
 | oracle | Events rule | not supported (warning) – filter in your handler | bucket must have "Emit Object Events" enabled |
 | tencent | COS trigger | native | bucket name must be `<name>-<APPID>`, e.g. `uploads-1250000000` |
 | huawei | OBS trigger | native | |
+| onprem | a directory of files | prefix/suffix in the host | `created` and `deleted`. `builtin` creates the directory; `{use: directory, path}` uses one you already have. The first start records current files and does not emit them |
 
 Example: [`examples/05-storage-events`](../examples/05-storage-events).
 
@@ -188,6 +192,7 @@ Example: [`examples/05-storage-events`](../examples/05-storage-events).
 | azure | Service Bus topic + subscription | not applied (warning); `existing` needs `options.servicebus_namespace_id` and `options.servicebus_connection` |
 | alibaba | MNS topic | `filter.tag` (string) only |
 | huawei | SMN topic | – |
+| onprem | file topic, fan-out | exact match on attributes, then on JSON body fields |
 
 Example: [`examples/06-pubsub-topic`](../examples/06-pubsub-topic).
 

{py_serverless_kit-0.1.3 → py_serverless_kit-0.3.0}/docs/getting-started.md

@@ -109,6 +109,7 @@ pskit runs Terraform, so credentials come from each Terraform provider's standar
 | `tencent` | `TENCENTCLOUD_SECRET_ID` / `TENCENTCLOUD_SECRET_KEY`, or `options.profile` |
 | `huawei` | `HW_ACCESS_KEY` / `HW_SECRET_KEY` (+ `HW_REGION_NAME`), or `options.profile` |
 | `cloudflare` | `CLOUDFLARE_API_TOKEN`. `options.account_id` is required |
+| `onprem` | local: nothing to configure (the Python that runs `pskit` starts the host). Remote: OpenSSH and `options.deploy.method: ssh`, or Docker and `method: docker`. Servers without Python: `python: bundle` or Docker |
 
 Provider-specific required options are listed in [providers.md](providers.md).
 

{py_serverless_kit-0.1.3 → py_serverless_kit-0.3.0}/docs/handlers.md

@@ -156,6 +156,7 @@ def worker(event, ctx):
 | Provider | Behaviour |
 |---|---|
 | aws (SQS) | becomes `batchItemFailures`, so only the failed messages are retried |
+| onprem | the host retries only the failed message ids, and moves a message to `dead_letter` after `max_receive` |
 | local | printed as `batchItemFailures` |
 | everyone else | any failure raises `BatchFailure`, so the whole delivery is retried |
 
@@ -173,7 +174,7 @@ invoke("audit", {"order_id": 42}, asynchronous=True)          # fire and forget
 How the target is resolved:
 
 1. If `PSKIT_ENDPOINT_<NAME>` is set (`billing` → `PSKIT_ENDPOINT_BILLING`, non-alphanumerics become `_`), pskit POSTs to that http(s) URL. This works on any provider.
-2. `local` (CLI, tests): calls the handler in-process.
+2. `local` (CLI, tests) and `onprem`: call the handler in-process. `asynchronous=True` still finishes before `invoke()` returns.
 3. `aws`: `lambda:InvokeFunction` via boto3 (`pip install py-serverless-kit[aws]`, and add `boto3` to requirements). Grant `lambda:InvokeFunction` in `iam.statements`.
 4. `gcp`: authenticated HTTPS call to `https://<region>-<project>.cloudfunctions.net/<service>-<stage>-<name>` with an ID token from the metadata server.
 5. Other providers raise `InvokeError` unless `PSKIT_ENDPOINT_<NAME>` is set. Point it at the target's HTTP URL from `pskit info`. On Azure, invoke-only functions expose `POST /_pskit/invoke/<name>` (function key required).
@@ -186,7 +187,8 @@ pskit injects:
 
 | Variable | Value |
 |---|---|
-| `PSKIT_PROVIDER` | `aws`, `gcp`, … (`local` under the CLI) |
+| `PSKIT_PROVIDER` | `aws`, `gcp`, `onprem`, … (`local` under the CLI) |
+| `PSKIT_ONPREM_ROOT` | on-premises only: directory of the running host. Handlers use it to publish into the file broker |
 | `PSKIT_SERVICE`, `PSKIT_STAGE`, `PSKIT_REGION` | deployment identity |
 | `PSKIT_FUNCTION`, `PSKIT_HANDLER` | the logical function and its handler (not app settings on Azure, where they're passed explicitly) |
 | `PSKIT_GCP_PROJECT` | GCP only |

{py_serverless_kit-0.1.3 → py_serverless_kit-0.3.0}/docs/local-development.md

@@ -92,6 +92,10 @@ def test_workflow():
 | `LocalRunner(project, env_file=".env")` | in-process runner |
 | `runner.invoke(function, event)` | run a handler; HTTP returns a `Response` |
 | `runner.run_workflow(name, data, sleep=False)` | returns `{"output", "history"}`; raises `WorkflowFailed` |
+
+## On-premises is a deploy, not `pskit dev`
+
+`pskit dev` reloads HTTP handlers and drops the process when you stop it. `provider.name: onprem` is the durable run: `pskit deploy` starts a process that keeps schedules, file queues, directory storage, topics and embedded workflows after the command returns. `options.deploy.method` is `local` (this machine), `ssh`, or `docker`. See [providers.md](providers.md#onprem-on-premises), [`examples/16-on-premises`](../examples/16-on-premises) and [`examples/17-on-premises-remote`](../examples/17-on-premises-remote).
 | `http_event(method, path, body=None, headers=None, query=None)` | dict/list bodies are JSON-encoded; `?query` in `path` is parsed |
 | `build_event(type, data, **http)` | `queue`/`topic` (list → records), `storage` (`{"bucket", "key", "size", "action"}`), `schedule`, `invoke`, `workflow`, `http` |
 

{py_serverless_kit-0.1.3 → py_serverless_kit-0.3.0}/docs/providers.md

@@ -14,12 +14,13 @@ Run `pskit providers` (or `pskit providers --json`) to print this matrix from th
 | [`digitalocean`](#digitalocean-functions) | beta | ✓ | ✓ | – | – | – | embedded | 3.9, 3.11 | 900 s |
 | [`oracle`](#oracle-oci-functions) | experimental | ✓ | – | – | ✓ | – | embedded | 3.9, 3.11 | 300 s |
 | [`cloudflare`](#cloudflare-python-workers) | experimental | ✓ | ✓ | – | – | – | embedded | 3.11–3.13 | 900 s |
+| [`onprem`](#onprem-on-premises) | experimental | ✓ | ✓ | ✓ | ✓ | ✓ | embedded | 3.9–3.14 | 3600 s |
 
 **Tiers**
 
 - **stable:** the generated Terraform is validated against the real provider plugin, and the full trigger set is supported.
 - **beta:** validated with `terraform validate`; event payload formats follow vendor documentation.
-- **experimental:** works with notable constraints (container images, Pyodide), so read the section below first.
+- **experimental:** works with notable constraints (container images, Pyodide, or a process on your own machine), so read the section below first.
 
 **Common to all providers**
 
@@ -27,7 +28,7 @@ Run `pskit providers` (or `pskit providers --json`) to print this matrix from th
 - Resources are tagged or labelled with `pskit-service`, `pskit-stage` and `managed-by: py-serverless-kit` where the cloud supports tags.
 - With no pinned `runtime`, pskit picks python3.12 or the newest version below it that the cloud supports (see [configuration.md](configuration.md#default-runtime)).
 
-Every generated configuration (all 10 providers) passes `terraform validate`. The repository's `scripts/validate_all_providers.py` re-checks this in CI.
+Every generated configuration (all 11 providers) passes `terraform validate`. The repository's `scripts/validate_all_providers.py` re-checks this in CI. On-premises uses Terraform's built-in provider, so that check does not download a plugin for it.
 
 ---
 
@@ -353,6 +354,104 @@ One Worker script per function. pskit generates a single Python module per Worke
 
 ---
 
+## onprem (On-premises)
+
+- **Terraform:** built-in `terraform_data` (no plugin download). Create/destroy run `onprem_deploy.py` via `local-exec`
+- **Credentials:** none for `method: local`. SSH keys / an SSH agent for `method: ssh`. Docker CLI (and optional `DOCKER_HOST`) for `method: docker`
+- **Dependencies:** native pip wheels for a local host; manylinux / Windows / macOS wheels matching `deploy.target_os` and `architecture` for a remote host. `tzdata` is vendored so cron timezones work on Windows
+
+```yaml
+provider:
+  name: onprem
+  region: local
+  options:
+    host: 127.0.0.1          # bind address on the *target*. 0.0.0.0 is advertised as 127.0.0.1 unless advertise is set
+    port: 8080               # 1-65535. Give each service its own port
+    advertise: https://fn.internal.example   # optional URL written into outputs
+    data_dir: .pskit/onprem-data             # default .pskit/onprem-data/<service>-<stage> (local); <path>/data on SSH
+    poll_seconds: 0.5
+    admin_token: "${env:PSKIT_ADMIN_TOKEN, }"  # header x-pskit-token on /__pskit/* except health
+    services:
+      schedule: builtin                        # the only schedule implementation
+      queue: builtin                           # or {use: directory, path: /var/pskit/queues}
+      storage: {use: directory, path: .onprem/buckets}
+      topic: builtin
+      workflow: embedded                       # builtin is an alias of embedded
+    deploy:
+      method: local          # local | ssh | docker   (default local)
+```
+
+`pskit deploy` writes the bundle under `.pskit/onprem-<stage>/onprem_app/` and runs `onprem_deploy.py apply`. `pskit remove` stops the process (or container / systemd unit) and does not delete `data_dir`.
+
+Omitted services default to `builtin` and are created at start. `existing: true` on one queue, bucket or topic skips that create and waits until the directory appears. Names are a single path segment (`..`, slashes and NUL are rejected).
+
+| Trigger | Implementation |
+|---|---|
+| http | the host process. `auth` must be `none` (check tokens in the handler) |
+| schedule | in-process rate (any positive number of minutes, hours or days, including values that are not cron) and 5-field cron. A missing IANA timezone warns and is evaluated in UTC |
+| queue | one JSON file per message. `batch_size`, `batch_window`, `visibility_timeout` (default `max(30, 6 x timeout)`), `dead_letter`, `max_receive` and `fifo` are honoured. `BatchResult` retries only the failed ids |
+| storage | files under `<bucket>/<key>`. `prefix`, `suffix`, `created` and `deleted`. The first start records the current files and does not emit them |
+| topic | fan-out. `filter` is an exact match on message attributes, then on JSON body fields |
+| workflows | embedded engine inside the host, so a workflow is not cut off by a function timeout |
+
+Publish from outside the process:
+
+| Request | Effect |
+|---|---|
+| `GET /__pskit/health` | status, no token |
+| `POST /__pskit/queues/<name>` | enqueue one JSON value, a list, or `{"messages": [...]}`. `202 {"queued": [ids]}` |
+| `GET /__pskit/queues/<name>` | `{"depth": n}` |
+| `POST /__pskit/topics/<name>` | publish, then deliver. `{"message", "attributes"}` sets attributes when those are the only keys |
+| `PUT` / `DELETE /__pskit/storage/<bucket>/<key>` | write or remove an object, then deliver |
+| `POST /__pskit/invoke/<function>` | in-process invoke |
+| `POST /__pskit/workflows/<name>` | run the embedded workflow |
+
+From a handler in that process (`PSKIT_ONPREM_ROOT` is set), call `submit_queue`, `submit_topic`, `put_object` or `delete_object` in `py_serverless_kit.runtime.onprem_host`.
+
+**Deploy targets** (`options.deploy`)
+
+| `method` | What runs | Target needs | Laptop needs |
+|---|---|---|---|
+| `local` (default) | detached process on this machine | Python (the interpreter that runs `pskit`) | — |
+| `ssh` | process or systemd unit on a remote host | SSH. Python only if `python: system` | OpenSSH (`ssh`, `scp`) |
+| `docker` | `docker build` + `docker run` | Docker engine, not Python | Docker CLI; set `docker_host: ssh://user@host` to use a remote daemon |
+
+When the server has **no Python**, use `python: bundle` (a portable CPython from [python-build-standalone](https://github.com/astral-sh/python-build-standalone) is fetched at apply and copied with the app) or `method: docker` (the image is `FROM python:<minor>-slim`). Air-gapped: `python_home` (copy a tree you already have) or `python_url` + `python_sha256` (internal mirror of an `install_only` tarball).
+
+```yaml
+# SSH + portable CPython + systemd (server does not need Python)
+deploy:
+  method: ssh
+  host: 10.0.1.12                 # or deploy: ssh://pskit@10.0.1.12/opt/pskit/orders
+  user: pskit
+  port: 22
+  identity_file: ${env:PSKIT_SSH_KEY}   # optional; otherwise the SSH agent
+  known_hosts: accept-new         # accept-new | ignore | path to a known_hosts file
+  path: /opt/pskit/orders
+  python: bundle                  # auto | system | bundle
+  target_os: linux                # auto | linux | windows | darwin
+  target_arch: x86_64             # auto | x86_64 | arm64  (drives pip wheels)
+  install: systemd                # process | systemd (linux only)
+  sudo: true                      # needed to write /etc/systemd/system
+
+# Docker (server needs Docker, not Python)
+deploy:
+  method: docker
+  image: pskit/orders:dev
+  docker_host: ssh://pskit@10.0.1.12   # empty = Docker on this laptop
+  restart: unless-stopped
+```
+
+`options.host` is the bind address **on the target**. Use `0.0.0.0` so other machines can call a remote host. `advertise` is the URL stored in `pskit info`. SSH deploy defaults `advertise` to `http://<ssh host>:<port>` when it is unset.
+
+**Resources:** `terraform_data.host` with create (`onprem_deploy.py apply`) and destroy (`onprem_deploy.py destroy`) `local-exec` provisioners.
+
+**Limits:** no cloud authorizer and no IAM mapping. A `terraform.extra` resource from another cloud (`aws_*`, `google_*`, `azurerm_*`, and the other cloud prefixes) is omitted with a warning. A state backend of `s3`, `gcs` or `azurerm` warns; set `provider.state.backend` empty (see `providers.onprem` in examples 11 and 15) to keep state on this machine. Delivery is at-least-once. A missed schedule fires once on the next poll, not as a burst. The host does not kill a handler at `timeout`; `ctx.remaining_time_ms()` still counts down. If `method` is `local` and `provider.runtime` is not the interpreter running `pskit`, validation warns and the host still uses that interpreter. `python: bundle` needs network on first apply unless `python_home` or a cached archive under `~/.cache/pskit/python-standalone` is present. systemd units are written to `/etc/systemd/system` (set `sudo: true` unless the SSH user is root).
+
+Examples: [`examples/16-on-premises`](../examples/16-on-premises) (local process), [`examples/17-on-premises-remote`](../examples/17-on-premises-remote) (SSH / Docker / bundled Python).
+
+---
+
 ## Writing your own provider
 
 See [architecture.md](architecture.md#third-party-providers) and [`deploy_docs/CONTRIBUTING.md`](../deploy_docs/CONTRIBUTING.md).

{py_serverless_kit-0.1.3 → py_serverless_kit-0.3.0}/docs/troubleshooting.md

@@ -82,6 +82,7 @@ Add `-v` to any command to see the full traceback. Start with `pskit validate`,
 | digitalocean | `doctl` must be installed and authenticated (`doctl auth init`); `options.namespace` required; set `options.api_host` to get URLs |
 | ibm | HTTP only, python3.11 only, 120 s / 4 GB max; large bundles → `options.code_reference` |
 | cloudflare | Pyodide: only stdlib and Pyodide packages; `options.account_id` and `CLOUDFLARE_API_TOKEN` required; non-`.py` files aren't uploaded |
+| onprem | one process per service, so give each service its own `options.port`. `pskit remove` stops it and leaves `data_dir`. `auth` must be `none`. A cloud `terraform.extra` resource is omitted. Set `state.backend` empty when the file points at S3, GCS or Azure Storage. Remote SSH needs `ssh`/`scp` on the laptop; a server without Python needs `deploy.python: bundle` or `method: docker`. systemd writes `/etc/systemd/system` (`sudo: true`). Bind `options.host: 0.0.0.0` on a remote host so other machines can call it |
 | alibaba / tencent / huawei | `iam.statements` aren't translated; set `iam.role` |
 
 ## FAQ

{py_serverless_kit-0.1.3 → py_serverless_kit-0.3.0}/docs/workflows.md

@@ -3,7 +3,7 @@
 A workflow chains functions with branching, retries, error handling, waits, parallel branches and fan-out. You define it once in `pskit.yml`, and pskit runs it:
 
 - **natively**, as AWS Step Functions (ASL) or Google Cloud Workflows;
-- on the **embedded engine** on every other cloud, inside an auto-generated orchestrator function;
+- on the **embedded engine** on every other target, inside an auto-generated orchestrator function (on premises that function runs inside the long-lived host, so the workflow is not cut off by a function timeout);
 - **locally** with `pskit workflow run`, using the same engine.
 
 ```yaml

{py_serverless_kit-0.1.3 → py_serverless_kit-0.3.0}/examples/01-hello-http/pskit.yml

@@ -15,6 +15,9 @@ providers:
   azure:
     region: eastus
     options: {subscription_id: "${env:ARM_SUBSCRIPTION_ID, 00000000-0000-0000-0000-000000000000}"}
+  onprem:
+    region: local
+    options: {host: 127.0.0.1, port: 8081}
 
 functions:
   hello:

{py_serverless_kit-0.1.3 → py_serverless_kit-0.3.0}/examples/02-rest-api/pskit.yml

@@ -80,3 +80,9 @@ providers:
     functions:
       admin-stats:
         events: [{http: GET /admin/stats}]
+  onprem:
+    region: local
+    options: {host: 127.0.0.1, port: 8082}
+    functions:
+      admin-stats:
+        events: [{http: GET /admin/stats}]

{py_serverless_kit-0.1.3 → py_serverless_kit-0.3.0}/examples/03-scheduled-jobs/pskit.yml

@@ -47,3 +47,6 @@ providers:
     options: {subscription_id: "${env:ARM_SUBSCRIPTION_ID, 00000000-0000-0000-0000-000000000000}"}
     functions:
       cleanup: {timeout: 600}            # Azure consumption plan maximum
+  onprem:
+    region: local
+    options: {host: 127.0.0.1, port: 8083}

{py_serverless_kit-0.1.3 → py_serverless_kit-0.3.0}/examples/04-queue-worker/README.md

@@ -20,6 +20,7 @@ return result
 | Cloud | What `BatchResult` does |
 | --- | --- |
 | AWS SQS | partial batch response: only failed messages are retried |
+| On-premises | partial batch response: only failed messages are retried, then dead-lettered |
 | GCP Pub/Sub, Azure Storage Queues, others | any failure fails the invocation, so the whole batch is redelivered |
 
 Make processing **idempotent**: on most clouds a message can be delivered more than once.
@@ -34,6 +35,8 @@ Make processing **idempotent**: on most clouds a message can be delivered more t
 | `fifo` | SQS FIFO | warning | not supported |
 | `existing: true` | look up instead of create | yes | yes |
 
+On premises every option in the YAML is implemented by a directory of message files. `builtin` (the default) creates that directory at start. `{use: directory, path: ...}` under `provider.options.services.queue` uses a directory you already have.
+
 `pskit validate --provider <cloud>` prints the warnings for your configuration.
 
 ## The producer
@@ -53,7 +56,7 @@ def send_job(job: dict) -> None:
     ...
 ```
 
-The example's `enqueue` handler only logs, so it runs anywhere without credentials.
+The example's `enqueue` handler logs on a cloud, so it runs anywhere without credentials. On premises (`PSKIT_ONPREM_ROOT`) it writes the job into the file queue with `submit_queue`.
 
 ## Run locally
 
@@ -77,4 +80,5 @@ pskit invoke -f enqueue -d '{"kind": "invoice", "id": 7}'    # 202
 pskit deploy                    # SQS queues + DLQ + event source mappings
 pskit deploy --provider gcp     # Pub/Sub topics + Eventarc triggers
 pskit deploy --provider azure   # Storage queues + queue triggers
+pskit deploy --provider onprem  # file queues on this machine, http://127.0.0.1:8084
 ```

{py_serverless_kit-0.1.3 → py_serverless_kit-0.3.0}/examples/04-queue-worker/app/worker.py

@@ -3,8 +3,8 @@
 ``event.records`` holds the messages of one batch. Return a ``BatchResult``
 naming the records that failed:
 
-* AWS SQS:         only those messages become visible again and are retried
-                   (``ReportBatchItemFailures`` is enabled for you);
+* AWS SQS and the on-premises host: only those messages become visible again
+                   and are retried (``ReportBatchItemFailures`` on AWS);
 * other clouds:    any failure fails the invocation, so the whole batch is redelivered.
 
 Either way a message that keeps failing ends up in the dead-letter queue
@@ -62,14 +62,20 @@ def _log_dead_letter(record: Record, ctx: Context) -> None:
 
 
 def enqueue(event: Event, ctx: Context):
-    """HTTP producer stub.
+    """HTTP producer.
 
-    Sending a message is a *cloud SDK* call (boto3 ``sqs.send_message``,
-    ``google-cloud-pubsub`` ``publish``, ``azure-storage-queue``
-    ``send_message`` ...). py-serverless-kit does not wrap these SDKs. Keep
-    that one call behind a small function of your own (see README), so the
-    rest of the handler stays portable.
+    On premises the host is in this process, so the message is written to the
+    file queue. On a cloud, publishing is a cloud SDK call (boto3
+    ``sqs.send_message``, ``google-cloud-pubsub`` ``publish``,
+    ``azure-storage-queue`` ``send_message``). Keep that call behind a small
+    function of your own (see README).
     """
     job = event.http.json()
-    ctx.logger.info("would enqueue", extra={"job": job, "queue": ctx.env.get("JOBS_QUEUE")})
-    return {"accepted": True, "queue": ctx.env.get("JOBS_QUEUE")}, 202
+    queue = ctx.env.get("JOBS_QUEUE") or "jobs"
+    if ctx.env.get("PSKIT_ONPREM_ROOT"):
+        from py_serverless_kit.runtime.onprem_host import submit_queue
+
+        message_id = submit_queue(queue, job)
+        return {"accepted": True, "queue": queue, "message_id": message_id}, 202
+    ctx.logger.info("would enqueue", extra={"job": job, "queue": queue})
+    return {"accepted": True, "queue": queue}, 202

{py_serverless_kit-0.1.3 → py_serverless_kit-0.3.0}/examples/04-queue-worker/pskit.yml

@@ -37,3 +37,6 @@ providers:
   azure:
     region: eastus
     options: {subscription_id: "${env:ARM_SUBSCRIPTION_ID, 00000000-0000-0000-0000-000000000000}"}
+  onprem:
+    region: local
+    options: {host: 127.0.0.1, port: 8084}

{py_serverless_kit-0.1.3 → py_serverless_kit-0.3.0}/examples/05-storage-events/pskit.yml

@@ -52,3 +52,12 @@ providers:
       audit-existing:
         events:
           - storage: {bucket: audit-uploads, events: [created]}
+  onprem:
+    region: local
+    options: {host: 127.0.0.1, port: 8085}
+    # The shared audit bucket is not on this machine. Create a local directory
+    # bucket with the host so the function has somewhere to listen.
+    functions:
+      audit-existing:
+        events:
+          - storage: {bucket: shared-uploads, events: [created, deleted]}

{py_serverless_kit-0.1.3 → py_serverless_kit-0.3.0}/examples/06-pubsub-topic/pskit.yml

@@ -25,3 +25,6 @@ providers:
   azure:
     region: eastus
     options: {subscription_id: "${env:ARM_SUBSCRIPTION_ID, 00000000-0000-0000-0000-000000000000}"}
+  onprem:
+    region: local
+    options: {host: 127.0.0.1, port: 8086}