Create the application by selecting the Markdown renderer template and setting at least the BASE variable.
- -1. In the [Gcore Customer Portal](https://portal.gcore.com), navigate to **FastEdge** > **HTTP Applications** > **Applications** and click **Create new application**. - -2. Scroll to **Create from a template** and click **Markdown renderer**. - -3. Enter a **Name** for the application. The name becomes part of the deployment URL. - -4. Fill in the **Template environment variables**: - - - **BASE** (required): The root URL of the Markdown source. The application appends the incoming request's path to this value when fetching files. Set it to the directory URL where the Markdown files live, with a trailing slash. Example: `https://raw.githubusercontent.com/G-Core/FastEdge-sdk-js/main/` - - - **HEAD** (optional): Raw HTML inserted verbatim into the `` tag of every rendered page. Use it to apply a stylesheet, set a viewport meta tag, or add any other head-level markup. Example: `` - -  - -5. (Optional) Configure additional sections: - - - **Response headers**: static headers added to every response, such as `Cache-Control` or CORS headers. - - **Environment variables**: additional runtime key-value pairs accessible via the SDK — separate from the template-defined variables above. - - **Secrets**: encrypted values from [Secrets Manager](/fastedge/secrets-manager/manage-secrets) for sensitive data such as API keys. The app reads each secret as an environment variable using the key name set here. - - **Edge Storage**: a key-value store the app can query at the edge. Requires an existing store on the [Edge Storage](/fastedge/kv-stores/manage-kv-store) page. - -6. Click **Save and deploy**. - -The application details page opens with the deployment URL in the format `https://
Request any Markdown file path from the app URL and inspect the response:
- -```sh -curl -i https://README
... -``` - -If `HEAD` is set, the injected markup appears inside ``. If the source file does not exist at the constructed URL, the app returns the upstream HTTP error code. - -To verify the source URL the app constructs, check that `BASE` + path matches the raw file URL directly — confirm `https://raw.githubusercontent.com/org/repo/main/README.md` returns HTTP 200 before deploying.
- -## Geolocation-based redirect - -The Geolocation-based redirect detects each visitor's country from Gcore's Geo-IP data and issues an HTTP 302 redirect to the corresponding URL. It's useful for routing international visitors to regional landing pages, language-specific subdomains, or data-residency-compliant endpoints without client-side JavaScript. - -Country rules are defined as environment variables: each key is an ISO 3166-1 alpha-2 country code and the value is the redirect URL. Visitors from countries with no matching rule are sent to the `DEFAULT` URL. - -### Step 1. Create the application - -Create the application by selecting the Geolocation-based redirect template, then configure the DEFAULT variable and country rules.
- -1. In the Customer Portal, navigate to **FastEdge** > **HTTP Applications** > **Applications** and click **Create new application**. - -2. Scroll to **Create from a template** and click **Geolocation-based redirect**. - -3. Enter a **Name** for the application. - -4. Fill in the **Template environment variables**: - - - **DEFAULT** (required): The fallback redirect URL for visitors whose country is not matched by any rule. Every deployment must have a default — without it, unmatched visitors receive an error. Example: `https://example.com/en` - -  - -5. Add country redirect rules in the **Environment variables** section. Each rule is one variable: - - - **Key**: ISO 3166-1 alpha-2 country code in uppercase. Example: `DE`, `FR`, `JP`, `US`. - - **Value**: The full redirect URL for visitors from that country. Example: `https://example.com/de`. - - Add as many country rules as needed. Country codes not listed here fall through to `DEFAULT`. - -6. (Optional) Configure **Response headers**, **Secrets**, and **Edge Storage** as needed. - -7. Click **Save and deploy**. - -The application details page opens with the deployment URL.
- -### Step 2. Test the application - -Send a request to the app URL and inspect the redirect response:
- -```sh -curl -i https://The redirect applies to all URL paths — `/pricing`, `/contact`, and `/` all redirect using the same country logic. To restrict redirects to the root path only, use a custom binary with a path check instead of this template.
- -Both templates are configured entirely through environment variables — no binary rebuild is needed to update the configuration after deployment. Country rules, redirect targets, and the Markdown source URL can all be changed from the application details page in the Customer Portal. diff --git a/fastedge/cache.mdx b/fastedge/cache.mdx index b146bcb00..9e1ad624d 100644 --- a/fastedge/cache.mdx +++ b/fastedge/cache.mdx @@ -4,25 +4,29 @@ sidebarTitle: Cache ai-navigation: Cache is a POP-local, strongly consistent key-value store available to FastEdge applications at runtime for transient state such as rate-limit counters, response memoization, and idempotency checks. It is distinct from Edge Storage, which is globally replicated and durable. --- -Cache is a fast key-value store co-located with each FastEdge POP (Point of Presence). It is intended for transient, request-time state ( counters, memoized computations, idempotency tokens ) and is available to every FastEdge application on a paid plan at runtime without needing to be created or linked in advance. +Cache is a fast key-value store co-located with each FastEdge POP (Point of Presence). It is intended for transient, request-time state — counters, memoized computations, idempotency tokens — and is available to every FastEdge application on a paid plan at runtime without needing to be created or linked in advance. -## How it works +All requests authenticate with an [API token](/account-settings/api-tokens). Set it as an environment variable before running the examples:
-1\. In the [Gcore Customer Portal](https://portal.gcore.com/accounts/reports/dashboard), navigate to **FastEdge** and choose the relevant page: **HTTP Applications** or **CDN Applications**. +```bash +export GCORE_API_KEY="{YOUR_API_KEY}" +``` -2\. On the **Templates** page, find the template you want to use to create an application. +## Create a template + +Creating a template requires two steps: upload a `.wasm` binary, then create the template referencing that binary. + +### Upload a binary + +Send the raw `.wasm` file as an `application/octet-stream` body: + +```bash +curl -X POST https://api.gcore.com/fastedge/v1/binaries/raw \ + -H "Authorization: APIKey $GCORE_API_KEY" \ + -H "Content-Type: application/octet-stream" \ + --data-binary @my-app.wasm +``` + +The response contains the binary ID: + +```json +{ + "id": 4748, + "api_type": "wasi-http", + "status": 1 +} +``` + +The `api_type` is determined by the binary and cannot be set manually. Use the returned `id` as the `binary_id` in the next step. + +### Create the template + +```bash +curl -X POST https://api.gcore.com/fastedge/v1/template \ + -H "Authorization: APIKey $GCORE_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "My template", + "short_descr": "Short description shown in the template list", + "long_descr": "Full usage instructions shown at deployment time.", + "binary_id": BINARY_ID, + "owned": true, + "params": [ + { + "name": "BASE_URL", + "data_type": "string", + "descr": "Base URL for the application", + "mandatory": true + } + ] + }' +``` + +The response contains the created template: + +```json +{ + "id": 174, + "name": "My template", + "api_type": "wasi-http", + "short_descr": "Short description shown in the template list", + "long_descr": "Full usage instructions shown at deployment time.", + "owned": true +} +``` + +Template names may only contain letters, digits, spaces, underscores, and hyphens. + +The application URL appears on the details page. Test it:
+ +```sh +curl https://The application fetches the upstream API, takes the first five users, and returns them:
+ +```json +{ + "count": 5, + "users": [ + {"id": 1, "name": "Leanne Graham", "username": "Bret", "email": "Sincere@april.biz"}, + {"id": 2, "name": "Ervin Howell", "username": "Antonette", "email": "Shanna@melissa.tv"} + ] +} +``` + +An [API token](/account-settings/api-tokens) is required.
+ +```bash +export GCORE_API_KEY="{YOUR_API_KEY}" +``` + +The URL from the create-app response becomes active within a few seconds:
+ +```bash +curl https://my-outbound-fetch-1000503.fastedge.app/ +``` + +The application fetches the upstream API, takes the first five users, and returns them:
+ +```json +{ + "count": 5, + "users": [ + {"id": 1, "name": "Leanne Graham", "username": "Bret", "email": "Sincere@april.biz"}, + {"id": 2, "name": "Ervin Howell", "username": "Antonette", "email": "Shanna@melissa.tv"} + ] +} +``` + +Skip this step when deploying from a template — go directly to [Step 2](#step-2-deploy-the-application).
Required: [Rust and Cargo](https://rustup.rs). On Windows, also install [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022) with the **Desktop development with C++** workload.
- ```sh - curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh - ``` +1. Add the Wasm compilation target: - 2\. Add the Wasm compilation target to Rust compiler: + ```sh + rustup target add wasm32-wasip2 + ``` - ```sh - rustup target add wasm32-wasip1 - ``` +2. Scaffold an application from the `http-base` template: - #### Step 2. Prepare the directory structure and a configuration file + ```sh + npm create fastedge-app@latest my-rust-app -- --rust --template http-base --no-verify + ``` - 1\. Initialize the directory structure: +3. Build the Wasm binary: - ```sh - cargo new myapp --lib - ``` + ```sh + cd my-rust-app + cargo build --release + ``` - 2\. Create a directory: +The Wasm file is written to `./target/wasm32-wasip2/release/basic_wasi_http.wasm`. Upload this file in Step 2.
- ```sh - mkdir myapp/.cargo - ``` +Required: [Node.js](https://nodejs.org).
- ```toml - [build] - target = "wasm32-wasip1" - ``` +1. Scaffold an application from the `http-base` template: - 4\. Create the project manifest file `myapp/Cargo.toml` with the following content: + ```sh + npm create fastedge-app@latest my-first-app -- --javascript --template http-base --no-verify + ``` - ```toml - [package] - name = "myapp" - version = "0.1.0" - edition = "2021" +2. Build the Wasm binary: - [lib] - crate-type = ["cdylib"] + ```sh + cd my-first-app + npm install + npm run build + ``` - [dependencies] - fastedge = "0.2" - ``` +The Wasm file is written to `./wasm/basic-http.wasm`. Upload this file in Step 2.
- #### Step 3. Create a source +Two deployment methods are available: from a custom binary built in Step 1, or from a preconfigured template — no binary is required for templates.
- ``` - use fastedge::{ - body::Body, - http::{Request, Response, StatusCode, Error}, - }; +### From a binary - #[fastedge::http] - fn main(_req: Request) -> ResultUse this method when deploying a Wasm binary built with the Rust or JavaScript SDK in Step 1.
- #### Step 4. Compile a Wasm file +1. In the [Gcore Customer Portal](https://portal.gcore.com), navigate to **FastEdge** > **HTTP Applications** > **Applications** and click **Create new application**. - Produce the Wasm binary: +  - ```sh - cargo build --release - ``` +2. On the **Create an application** page, click the **Upload binary** card. - The resulting Wasm code will be written to the `myapp/target/wasm32-wasip1/release/myapp.wasm` file. +  - -The application details page opens with the deployment URL.
-Use this method to deploy a built-in or custom template without writing or building any code.
- 3\. Click **Upload binary**. +1. In the Customer Portal, navigate to **FastEdge** > **HTTP Applications** > **Applications** and click **Create new application**. -  +  - 4\. Choose your custom binary file. +2. Scroll to the **Create from a template** section and select a template. Built-in templates are **Geolocation-based redirect** and **Markdown renderer**. To deploy from a custom template, create it first on the **HTTP Applications** > **Templates** page as described in [custom templates](/fastedge/create-manage-templates). -  +  - 5\. Enter a name for your application and provide a description if needed. +3. Enter a **Name** for the application and an optional description. - 6\. (Optional) Click **\+ Add response headers** to add fixed headers to the responses. For example, you may include CORS (cross-origin resource sharing) headers in each response to ensure secure communication between origins. +4. Fill in the **Template environment variables** required by the selected template: - 7\. (Optional) If you want to customize the behavior of your application, click **\+ Add environment variables** and enter your data as key-value pairs. + **Markdown renderer** -  + - **BASE** (required): Base URL for Markdown source files. Example: `https://raw.githubusercontent.com/G-Core/FastEdge-sdk-js/main/` + - **HEAD** (optional): HTML inserted into the `` tag. Example: `` -The application details page opens with the deployment URL.
- 2\. In the top-right corner of the screen, click **Create new application**. + -  +## Step 3. Test the application - 3\. In the **Create from a template** section, select the preferred template. +Click the URL at the top of the application details page to open the application in a browser, or test with curl:
-  +```sh +curl -i https://To find the URL later, navigate to **FastEdge** > **HTTP Applications** > **Applications** and check the **URL** column.
- 5\. Provide environment variables or any required configuration for your app. Note that the list of setup options depends on the selected template. For example, if you create a FastEdge app from a Markdown template, you need to add response headers, enter the base part of the origin URL, and add content from the `` section of an HTML document. + - 6\. (Optional) If you want to add metadata to the configuration, click **\+ Add environment variables** and enter metadata as key-value pairs. +Set this variable before running the examples:
-  +```bash +export GCORE_API_KEY="{YOUR_API_KEY}" +``` - You can now test its configuration and adjust it as described in the following steps. +## Step 1. Build a Wasm binary - - +Build the binary using the Rust or JavaScript SDK. Set `WASM_PATH` at the end of the tab — it is used in Step 2.
-### Via command line +Required: [Rust and Cargo](https://rustup.rs). On Windows, also install [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022) with the **Desktop development with C++** workload.
-```sh -curl -X 'POST' - 'https://api.gcore.com/fastedge/v1/binaries/raw' \ - -H 'accept: application/json' - -H 'Authorization: APIKey api_key' - -H 'Content-Type: application/octet-stream' - --data-binary '@./dist/main.wasm' +```bash +rustup target add wasm32-wasip2 +npm create fastedge-app@latest my-rust-app -- --rust --template http-base --no-verify +cd my-rust-app && cargo build --release +export WASM_PATH="./target/wasm32-wasip2/release/basic_wasi_http.wasm" ``` -In the response, you will receive the ID of the uploaded binary (`Required: [Node.js](https://nodejs.org).
-```sh -curl -X 'POST' - 'https://api.gcore.com/fastedge/v1/apps' - -H 'name: app_name' - -H 'accept: application/json' - -H 'client_id: 0' - -H 'Authorization: APIKey api_key' - -H 'Content-Type: application/json' - -d '{ - "binary": binary_id, - "plan": "beta", - "status": 1 -}' +```bash +npm create fastedge-app@latest my-first-app -- --javascript --template http-base --no-verify +cd my-first-app && npm install && npm run build +export WASM_PATH="./wasm/basic-http.wasm" ``` -Where: +Deploying requires two calls: upload the binary, then create the application referencing the returned binary ID.
-You can test the application after its deployment by clicking the application link on the deployment confirmation screen: +**1. Upload the binary** - -  - +| Parameter | Required | Description | +|-----------|----------|-------------| +| Request body | Yes | Raw Wasm binary as `application/octet-stream` | -Additionally, you can inspect and adjust the configuration in the Customer Portal on the **HTTP Applications** page: +The API returns:
- ```js - import { getEnv } from 'fastedge::env'; +```json +{"id": 4683, "api_type": "wasi-http", "status": 1, "checksum": "ba9dae6f9e5850833cd1929170916f2b"} +``` - async function eventHandler(event) { - const request = event.request; - const customEnvVariable = getEnv('MY_CUSTOM_ENV_VAR'); - const headersStr = JSON.stringify(Object.fromEntries(request.headers.entries()), null, 2); +```bash +export BINARY_ID="{id}" # replace with the id from the response above +``` - return new Response(`Headers: ${headersStr}\n`, { - headers: { - 'Custom-Header': customEnvVariable, - }, - }); - } +The API returns:
+ +```json +{"id": 2543, "name": "my-edge-app", "url": "https://my-edge-app-1000503.fastedge.app", "status": 1, "binary": 4683, "api_type": "wasi-http", "plan": "Free"} +```The deployment URL becomes active within a few seconds of creation. Send a request to the `url` from the create-app response:
+ +```bash +curl -i https://The `http-base` template returns a plain-text response:
+ +``` +HTTP/1.1 200 OK +content-type: text/plain;charset=UTF-8 + +Hello from FastEdge! +``` + +The application is now available in the CDN Applications list. To activate it, attach it to a CDN resource — the full walkthrough is in [CDN applications](/fastedge/getting-started/integrate-cdn-with-fastedge).
+ +Deploying requires two API calls: upload the binary to get its ID, then create the CDN application. An [API token](/account-settings/api-tokens) is required.
+ +```bash +export GCORE_API_KEY="{YOUR_API_KEY}" +``` + +The response contains the binary ID:
+ +```json +{"id": 4695, "api_type": "proxy-wasm", "checksum": "c083e2b6...", "source": 1, "status": 1} +``` + +### Create the application + +```bash +export BINARY_ID=4695 + +curl -sX POST 'https://api.gcore.com/fastedge/v1/apps' \ + -H "Authorization: APIKey $GCORE_API_KEY" \ + -H 'Content-Type: application/json' \ + -d "{\"name\": \"my-cdn-app\", \"binary\": $BINARY_ID, \"status\": 1}" +``` + +The response contains the application ID:
+ +```json +{"id": 2553, "name": "my-cdn-app", "binary": 4695, "api_type": "proxy-wasm", "plan": "Free", "plan_id": 30, "status": 1} +``` + +To activate the application, attach it to a CDN resource. Attachment steps — including the CDN API call — are in [CDN applications](/fastedge/getting-started/integrate-cdn-with-fastedge).
+ +The application URL appears on the details page. Test it:
+ +```sh +curl -i https://Deploying requires two API calls: upload the binary to get its ID, then create the application. An [API token](/account-settings/api-tokens) is required.
+ +```bash +export GCORE_API_KEY="{YOUR_API_KEY}" +``` + +The response contains the binary ID:
+ +```json +{"id": 4695, "api_type": "wasi-http", "status": 1} +``` + +**2. Create the application** + +```bash +export BINARY_ID=4695 + +curl -sX POST 'https://api.gcore.com/fastedge/v1/apps' \ + -H "Authorization: APIKey $GCORE_API_KEY" \ + -H 'Content-Type: application/json' \ + -d "{\"name\": \"my-http-app\", \"binary\": $BINARY_ID, \"status\": 1}" +``` + +The response contains the application URL:
+ +```json +{"name": "my-http-app", "url": "https://my-http-app-1000503.fastedge.app", "api_type": "wasi-http"} +``` + +**3. Test** + +The URL becomes active within a few seconds:
+ +```bash +curl -i https://my-http-app-1000503.fastedge.app/hello +``` + +Deploy an application from a predefined template or upload a custom binary. Custom binaries must conform to the [Proxy-Wasm](https://github.com/proxy-wasm/spec) specification.
+ +A predefined template is available for JWT authentication. It verifies the JSON Web Token in the request `Authorization` header before the request reaches the origin.
+ +1. In the [Gcore Customer Portal](https://portal.gcore.com), navigate to **FastEdge**. +2. Open the **CDN Applications** page and click **Create new application**. + + + +3. In the **Create from a template** section, select **Validate JWT in Authorization header**. + + + +4. Enter a name for the application and, optionally, a description. +5. Add the required environment variables, such as a token signing key for authentication checks. + + + +6. Click **Save and deploy**. + +The application is deployed and ready to be linked to a CDN resource.
+ + + +To adjust the configuration later, click **Actions** > **Edit application**.
+ + + +Custom implementations are available in the [FastEdge-sdk-rust examples](https://github.com/G-Core/FastEdge-sdk-rust/examples) and [proxy-wasm-sdk-as examples](https://github.com/G-Core/proxy-wasm-sdk-as/examples) repositories.
+ +1. In the [Gcore Customer Portal](https://portal.gcore.com), navigate to **FastEdge**. +2. Open the **CDN Applications** page and click **Create new application**. + + + +3. Click **Upload binary**. + + + +4. Select the compiled `.wasm` file. + + + +5. Enter a name for the application and, optionally, a description. +6. Add any required environment variables as key-value pairs. For sensitive values, click **+ Add Secret** to store them in [Secrets Manager](/fastedge/secrets-manager/manage-secrets) instead. + + + +7. Click **Save and deploy**. + +The application is deployed and ready to be linked to a CDN resource. To adjust the configuration later, click **Actions** > **Edit application**.
+ + + +FastEdge can be enabled for all requests on a CDN resource, or limited to specific URL paths using CDN rules.
+ +URL-specific rules apply FastEdge logic only to certain paths — for example, protecting `/api/` with JWT validation while leaving other paths unaffected.
+ +1. In the Customer Portal, navigate to **CDN**. +2. Find the resource and open its settings. +3. Click **Rules** > **Create rule**. + + + +4. Click **Create blank rule**. +5. Enter a rule name. +6. In the **Match criteria** section, specify the URL paths affected by the application. +7. In the **Options** section, click **Add option**. +8. Scroll to the **FastEdge apps** section and enable the toggle for the required stage. + + + +9. Select the application from the dropdown. + + + +10. (Optional) Select the **Interrupt request processing in case of error** checkbox. + + + +To stop FastEdge processing on a CDN resource, disable the configured toggles and save.
+ +1. In the Customer Portal, navigate to **CDN**. +2. Find the resource and open its settings. + + + +3. To disable FastEdge for the **whole CDN resource**, disable the toggles in the **FastEdge apps** section. +4. To disable FastEdge for **specific URL paths**, open the **Rules** page and disable the toggle for the relevant rule. +5. Click **Save changes**. + +## Delete a CDN application + +All requests authenticate with an [API token](/account-settings/api-tokens). Set it as an environment variable before running the examples:
+ +```bash +export GCORE_API_KEY="{YOUR_API_KEY}" +``` + +## How it works + +The CDN runtime invokes a CDN application at five stages of the request lifecycle: + +- **on_request_headers:** when the CDN receives request headers, before cache. +- **on_request_headers_after_cache:** when the CDN receives request headers, after cache. +- **on_request_body:** when the CDN receives the request body. +- **on_response_headers:** before the CDN sends response headers to the client. +- **on_response_body:** before the CDN sends the response body to the client. + +Upload the compiled `.wasm` file to the FastEdge binary store. The API automatically detects the binary type from the file contents.
+ +```bash +curl -X POST https://api.gcore.com/fastedge/v1/binaries/raw \ + -H "Authorization: APIKey $GCORE_API_KEY" \ + -H "Content-Type: application/octet-stream" \ + --data-binary @app.wasm +``` + +The response includes the binary ID used in the next step:
+ +```json +{ + "id": 12345, + "api_type": "proxy-wasm" +} +``` + +To deploy from the predefined JWT template instead, list available templates with GET https://api.gcore.com/fastedge/v1/template, note the template's `binary` field, and use that binary ID in Step 2.
Create the application using the binary ID from Step 1. Set `status` to `1` to activate the application immediately.
+ +```bash +curl -X POST https://api.gcore.com/fastedge/v1/apps \ + -H "Authorization: APIKey $GCORE_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "my-cdn-app", + "binary": 12345, + "status": 1, + "env": { + "MY_VARIABLE": "value" + } + }' +``` + +The response includes the application ID (`id`), which is needed to configure the CDN resource:
+ +```json +{ + "id": 67890, + "name": "my-cdn-app", + "status": 1, + "api_type": "proxy-wasm" +} +``` + +## Step 3. Enable FastEdge for your CDN resource + +Update the CDN resource to route traffic through the FastEdge application. The `fastedge` option accepts five trigger stages — configure the ones the application handles.
+ +```bash +curl -X PATCH https://api.gcore.com/cdn/resources/RESOURCE_ID \ + -H "Authorization: APIKey $GCORE_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "options": { + "fastedge": { + "enabled": true, + "on_request_headers": { + "app_id": "67890", + "enabled": true, + "interrupt_on_error": true + } + } + } + }' +``` + +Replace `RESOURCE_ID` with the CDN resource ID. The `interrupt_on_error` field controls behavior on error: `true` returns the FastEdge error to the client, `false` forwards the request to the origin. For security-sensitive applications, set it to `true`.
+ +To apply FastEdge only to specific URL paths, create a CDN rule with POST https://api.gcore.com/cdn/resources/RESOURCE_ID/rules and include the `fastedge` option in the rule's `options` object.
Set `fastedge.enabled` to `false` to stop FastEdge processing on a CDN resource:
+ +```bash +curl -X PATCH https://api.gcore.com/cdn/resources/RESOURCE_ID \ + -H "Authorization: APIKey $GCORE_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "options": { + "fastedge": { + "enabled": false + } + } + }' +``` + +## Delete a CDN application + +A `204 No Content` response confirms the application was deleted.
-Bloom Filters are designed for fast membership checks on large datasets. Common use cases include IP blocklists, bot detection, deduplication, and cache pre-screening.
-- False positives are possible, but false negatives are not. -- The size of the Bloom Filter and the number of hash functions used affect its performance and accuracy. -- Once an element is added to a Bloom Filter, it cannot be removed. +Unlike a regular key-value store, applications do not use Bloom Filters to retrieve stored values. Instead, they answer one question: "Have I seen this value before?" Bloom Filters can return false positives — reporting a value as present when it is not — but never false negatives. Once a value is added, it cannot be removed individually.
+## Create a Bloom Filter -## Creating a Bloom Filter +Open the [Gcore Customer Portal](https://portal.gcore.com/accounts/reports/dashboard), navigate to **FastEdge**, and select **Edge Storage** in the sidebar. Click the store name to open it.
-1\. In the [Gcore Customer Portal](https://portal.gcore.com/accounts/reports/dashboard), navigate to **FastEdge** and choose the relevant page: **Edge Storage**. - -2\. Find the Edge Storage you want to edit and click its name to open it. - -3\. Click **Insert item** and select **Bloom Filter**. +1. Click **Insert item** and select **Bloom Filter**. -  +  -4\. Give the Bloom Filter a key, then click **Insert value** +2. Enter a key in the **Key** field. -  +  -5\. Add as many rows as you would like, providing the value. Values can be entered manually or uploaded from file. +3. Click **Insert value**. In the panel that opens, enter a value in the **Value** field. -  +  -Click **+ Add value** to get another entry row. - -To edit a Bloom Filter, open the store that contains it. In the item list, click the three-dot icon next to the Bloom Filter and select **Edit**.
-  +  -4\. You are now able to add more values. Editing existing values or deleting values is not available. +The editor lists the current values and a search box. Click **Insert value** to open the value panel, add entries, and click **Save Bloom Filter** to apply.
-  +  -The probabilistic nature of this data structure prevents you from changing existing values. +To delete a Bloom Filter, open the store that contains it. Click the three-dot icon next to the Bloom Filter and select **Delete**. Confirm the deletion when prompted.
-1\. In the [Gcore Customer Portal](https://portal.gcore.com/accounts/reports/dashboard), navigate to **FastEdge** and choose the relevant page: **Edge Storage**. +Bloom Filters are managed through the same data endpoint as key-value pairs. Use datatype: bloom_filter in all operations.
A Bloom Filter is stored as a single key inside an Edge Storage store. The key identifies the filter, while the payload contains its values.
+ +Use PUT /fastedge/v1/kv/{store_id}/data with op: add to create a Bloom Filter. The payload is an array of values, each with an encoding and a value field.
The API returns write statistics:
+ +```json +{ + "write_count": 3, + "del_count": 0, + "write_size": 71, + "store_size": 356, + "revision": 602 +} +``` + +## Read a Bloom Filter + +The API exposes the stored values for management and debugging purposes. Applications typically use Bloom Filters for membership checks rather than value retrieval.
+ +Retrieve the values stored in a Bloom Filter with GET /fastedge/v1/kv/{store_id}/data/{key}:
The API returns the full value list:
+ +```json +{ + "datatype": "bloom_filter", + "key": "blocked-ips", + "payload": [ + { "encoding": "plain", "value": "192.168.1.1" }, + { "encoding": "plain", "value": "10.0.0.1" }, + { "encoding": "plain", "value": "172.16.0.5" } + ], + "count": 3 +} +``` + +## Add values + +Unlike sorted sets, Bloom Filters do not support updates or removals. New values can only be appended. Use the same PUT endpoint with op: add to add values to an existing filter. Values that are already present are ignored without error.
del_entries is not supported for Bloom Filters. Removing individual values would introduce false negatives and break the fundamental guarantee of the data structure — Bloom Filters are append-only by design. To reset a filter, delete it with op: del_key and recreate it.
+Use op: del_key to delete the entire Bloom Filter and all its values.
The API returns del_count: 1 on success.
Each store is a named container for key-value pairs. After creation, a store must be linked to a FastEdge application before the application can access it — linking instructions are in [Managing applications](/fastedge/manage-apps#edge-storage).
+Each store is a named container for key-value pairs. After creating a store, link it to a FastEdge application before the application can access its data — linking instructions are in [Managing applications](/fastedge/manage-apps#edge-storage).
+ +Data is replicated across Gcore's edge network, so reads are served from a local copy at the edge location handling each request.
## Create a store @@ -41,12 +43,14 @@ Edge Storage holds key-value data on Gcore's global edge network and makes it av ## Insert key-value pairs -Key-value pairs can be entered manually, loaded from a file, or set with an expiration date. Pairs can be added during the creation wizard (step 2) or at any time by clicking the store name in the Edge Storage list to open it.
+Key-value pairs are added through the **Insert item** panel inside the store view. Pairs can be added during the creation wizard (step 2) or at any time by clicking the store name in the Edge Storage list to open it.
### Add a pair manuallyClick **Insert item** and select **KV pair**. In the panel that opens, enter the key and value. Click **+ Add value** to add another row. Click **Save** to apply the changes.
+Keys are limited to 256 bytes.
+  @@ -55,39 +59,37 @@ Edge Storage holds key-value data on Gcore's global edge network and makes it av  -The panel also provides two additional options for each value in the same row:
- -- **Upload from file** — click the upload icon to load the value from a file instead of typing it. Text and binary files are supported — images, fonts, and similar assets. The maximum file size is 1 MB. After uploading, the portal displays a hash of the file content rather than the original filename. -- **Set expiration** — click the expiry icon to assign a date and time after which the value stops being returned to applications. It may remain visible in the portal briefly after expiration. +### Upload a value from a file -Keys are limited to 256 bytes.
+To load a value from a file instead of typing it, click the upload icon in the value row. Text and binary files are supported — images, fonts, and similar assets. The maximum file size is 1 MB. After uploading, the portal displays a hash of the file content rather than the original filename.
 +### Set an expiration date + +To assign an expiration to a value, click the expiry icon in the value row and select a date and time. After that point, the value stops being returned to applications. It may remain visible in the portal briefly after expiration.
+  ## Edit a key-value pair -Clicking a store name in the Edge Storage list opens the **Edit Edge Storage** page where all pairs are listed. To edit a pair, click the three-dot icon next to it, select **Edit**, update the value or expiration date, then click **Save**.
+Once pairs are in a store, individual values can be updated at any time. Clicking a store name in the Edge Storage list opens the **Edit Edge Storage** page where all pairs are listed. To edit a pair, click the three-dot icon next to it, select **Edit**, update the value or expiration date, then click **Save**.
Individual and bulk deletion are both available from inside the store view.
+To remove outdated or incorrect data, pairs can be deleted individually or in bulk. Open the store by clicking its name in the Edge Storage list to access both options.
To delete a single pair, click the three-dot icon next to it, select **Delete**, and confirm.
@@ -105,7 +107,11 @@ Additional pairs can be inserted from the edit view. Submitting a key that alreaThe external store must be publicly accessible. Gcore's edge nodes connect to it over the network on each request.
-**Hosted Edge Storage vs BYOD.** With hosted Edge Storage, data lives at every edge location globally and reads are served locally — latency is typically in the single-digit milliseconds. With BYOD, each read is a live query to the external database, so response time depends on the network distance between the edge location and the database host. BYOD is a practical choice for development, testing, or workloads where read speed is not critical. For latency-sensitive production workloads, hosted Edge Storage is recommended.
+## Hosted Edge Storage vs BYOD + +With hosted Edge Storage, data lives at every edge location globally and reads are served locally — latency is typically in the single-digit milliseconds. With BYOD, each read is a live query to the external database, so response time depends on the network distance between the edge location and the database host.
+ +BYOD is a practical choice for development, testing, or workloads where read speed is not critical. For latency-sensitive production workloads, hosted Edge Storage is recommended.
Supported URL schemes:
@@ -114,7 +120,7 @@ Additional pairs can be inserted from the edit view. Submitting a key that alreaURL format: `redis://:password@host:port/db-index` or `redis://username:password@host:port/db-index`
-### Create a BYOD store +## Create a BYOD storeFollow steps 1–3 from [Create a store](#create-a-store), then:
@@ -130,20 +136,14 @@ Additional pairs can be inserted from the edit view. Submitting a key that alrea 5. Click **Create Edge Storage** to validate the connection and create the store.After creation, link the BYOD store to a FastEdge application using the same process as a regular store — instructions are in [Managing applications](/fastedge/manage-apps#edge-storage). Once linked, the application accesses the BYOD store through the standard SDK API. The prefix is applied transparently and the application code does not need to know whether the store is BYOD or hosted.
@@ -153,7 +153,7 @@ A store cannot be converted between BYOD and hosted storage after creation. TheAutomate KV store management using the [Python SDK](/developer-tools/sdks/python) or [Go SDK](/developer-tools/sdks/go) for store-level operations, while key-value data operations require direct HTTP calls to the FastEdge REST API.
A Sorted Set (ZSET) stores unique members, each with a numeric score. Members are ordered by score, making sorted sets ideal for leaderboards, rankings, and priority-based lists. Adding the same member value again updates its score; ties in score are broken lexicographically.
-- Each member is unique; adding the same member updates its score. -- Scores are numeric; members are ordered by score, then lexicographically for ties. -- Membership is stored in-memory with scores, so very large sets can impact memory usage. +## Create a sorted set +Open the [Gcore Customer Portal](https://portal.gcore.com/accounts/reports/dashboard), navigate to **FastEdge**, and select **Edge Storage** in the sidebar. Click the store name to open it.
-## Creating a Sorted Set - -1\. In the [Gcore Customer Portal](https://portal.gcore.com/accounts/reports/dashboard), navigate to **FastEdge** and choose the relevant page: **Edge Storage**. - -2\. Find the Edge Storage you want to edit and click its name to open it. - -3\. Click **Insert item** and select **Sorted Set**. +1. Click **Insert item** and select **Sorted Set**. -  +  -4\. Give the Sorted Set a key, then click **Insert value** +2. Enter a key in the **Key** field. -  +  -5\. Add as many rows as you would like, providing a score and the value. Values can be entered manually or uploaded from file. +3. Click **Insert value**. In the panel that opens, enter a value in the **Value** field and a numeric score in the **Score** field. -  +  -Click **+ Add value** to get another entry row. - -To edit a sorted set, open the store that contains it. In the item list, click the three-dot icon next to the sorted set and select **Edit**.
-  +  -4\. You are now able to add more values, edit existing values or delete values. +The editor lists all current members and their scores. Add new members with **Insert value** or remove existing ones using the delete icon in each row. Click **Save Sorted Set** to apply the changes.
-5\. If everything is configured correctly, click **Save Sorted Set** in the top right corner. +## Delete a sorted set -## Deleting a Sorted Set +To delete a sorted set, open the store that contains it. Click the three-dot icon next to the sorted set and select **Delete**. Confirm the deletion when prompted.
-1\. In the [Gcore Customer Portal](https://portal.gcore.com/accounts/reports/dashboard), navigate to **FastEdge** and choose the relevant page: **Edge Storage**. +Sorted sets are managed through the same data endpoint as key-value pairs. Use datatype: sorted_set in all operations.
A sorted set is stored as a single key inside an Edge Storage store. The key identifies the set, while the payload contains its members and scores.
+ +Use PUT /fastedge/v1/kv/{store_id}/data with op: add to create a sorted set. The payload is an array of members, each with an encoding, a value, and a numeric score.
The API returns write statistics:
+ +```json +{ + "write_count": 3, + "del_count": 0, + "write_size": 78, + "store_size": 91, + "revision": 596 +} +``` + +## Read sorted set members + +Retrieve the members of a sorted set with GET /fastedge/v1/kv/{store_id}/data/{key}:
The API returns the full member list with scores:
+ +```json +{ + "datatype": "sorted_set", + "key": "leaderboard", + "payload": [ + { "encoding": "plain", "value": "player1", "score": 100 }, + { "encoding": "plain", "value": "player2", "score": 200 }, + { "encoding": "plain", "value": "player3", "score": 300 } + ], + "count": 3 +} +``` + +To list all entries in a store (including sorted sets), use GET /fastedge/v1/kv/{store_id}/data. Sorted sets appear with datatype: sorted_set but without member details in the list response.
Members are identified by value. If a member with the same value already exists, its score is replaced. Use the same PUT endpoint with op: add to add new members or update scores of existing ones.
Use op: del_entries to remove individual members while keeping the sorted set itself. Use op: del_key to remove the entire sorted set — see Delete a sorted set below.
The payload for del_entries requires only the encoding and value fields — score is not needed for deletion.
The API returns the number of deleted entries in del_count.
Use op: del_key to delete the entire sorted set and all its members.
The application management page provides access to all settings and runtime data for a deployed FastEdge application in one place.
-- **Template name**: If the application was created from a template, view the template and its configuration +To open the management page:
-- **Metrics**: Check response statuses for requests to the FastEdge servers and analyze runtime duration data. +1. In the [Gcore Customer Portal](https://portal.gcore.com/accounts/reports/dashboard), navigate to **FastEdge** and select either **HTTP Applications** or **CDN Applications**. -- **Logs**: View and enable application logs. +2. On the **Applications** page, click the three-dot icon next to the application and select **Manage**. -- **Response Headers**: Headers added to every response. + -- **Environment Variables**: Update or add environment variables. + -- **Secrets**: Update or add secrets (encrypted environment variables). +The following tabs are available on the management page:
-- **Edge Storage**: Update or add Edge Storage (key-value storage). +- **Metrics**: response status counts and runtime duration charts. +- **Logs**: enable log collection and filter log entries. +- **Response headers**: add HTTP headers to every application response. +- **Environment variables**: define configuration values the application reads at runtime. +- **Secrets**: link encrypted secrets from Secrets Manager to the application. +- **Edge Storage**: link key-value stores to the application. -To open the application management page: +The table below describes when to use each configuration option:
-1\. In the [Gcore Customer Portal](https://portal.gcore.com/accounts/reports/dashboard), navigate to **FastEdge** and choose the relevant page: **HTTP Applications** or **CDN Applications**. +| Feature | Use for | +|---------|---------| +| Response headers | HTTP headers added to every response — CORS, cache control, security headers | +| Environment variables | Configuration values available to the application at runtime, up to 64 KB each | +| Secrets | API keys, credentials, and other sensitive values encrypted at rest | +| Edge Storage | Shared mutable key-value data the application reads at runtime | +| Dictionary | Parameters over 64 KB and read-only edge node metadata — accessed from application code | -2\. On the **Applications** page, click the three-dot icon next to the application you want to configure. +## Application lifecycle -3\. Select **Manage**. +Use the **Actions** button in the page header to control the application lifecycle — stop or restart it, deploy a new binary, save its configuration as a reusable template, or delete it entirely.
- -  - +- **Stop** — pause the application. Stopped applications don't process requests. +- **Start** — resume a stopped application. +- **Edit application** — update the application name or description. +- **Update binary** — upload a new compiled Wasm binary. +- **Create template** — save the current configuration as a reusable template. +- **Delete** — permanently remove the application. -4\. Check and update your application's configuration as required. + -## Stop or start an application +An application may also stop automatically if payment for the product fails. In that case, it can't be restarted until payment is completed.
-You can change the running state of your application and decide if you want to have it running and processing requests, or stopped. The latter might be useful if you need to update the application's configuration or want to upload a new version of the application's binary file. +## Metrics -An application can be stopped for the following reasons: +The **Metrics** tab shows two charts: **Response Status** groups completed requests by HTTP status code, and **Runtime Duration (ms)** shows execution time per request in milliseconds. Use the time-range dropdown and the interval control in the chart header to adjust the view.
-- You manually stopped it, as described in the following instructions. You can restart the application at any time. +## Logs -- Payment for the product was unsuccessful. In this case, the application cannot be reactivated until payment is completed. +Logging is disabled by default. After enabling, the application records logs for 30 minutes, then stops automatically.
-To manually stop or activate the application: +To enable logging:
-1\. In the [Gcore Customer Portal](https://portal.gcore.com/accounts/reports/dashboard), navigate to **FastEdge** and choose the relevant page: **HTTP Applications** or **CDN Applications**. +1. Select the **Logs** tab. -2\. On the **Applications** page, click the three-dot icon next to the application you want to configure. +2. Turn on the **Enable logging** toggle. -3\. Select **Manage**. + -4\. Click **Actions** and choose the relevant one: **Stop** or **Start**. +The remaining logging time appears next to the toggle as **Minutes remaining: N**. To extend logging, turn the toggle off and on again.
- -  - +Log entries appear in the table with the following columns:
-The application status will be changed respectively. +- **Client IP address** — IP of the client that sent the request. +- **Timestamp (UTC)** — time the request was received. +- **Edge name** — identifier of the edge node that handled the request. +- **Request ID** — unique identifier assigned to the request. +- **Logs** — application log output for that request. -## View and enable logging +Use the text search field above the table to filter by log content, or select a date range. The **Refresh rate** dropdown controls how often the table updates — it defaults to 10 seconds when logging is active.
-If you want to record logs for your FastEdge application, make sure that you have the **Enable logging** toggle enabled. +## Application configuration - -  - +The **Response headers**, **Environment variables**, **Secrets**, and **Edge Storage** tabs each control a different aspect of how the application receives configuration and accesses external data at runtime. Click **Save changes** to apply any edits. The dictionary is a separate read-only data source that the application accesses directly from code.
-By default, FastEdge applications don't generate logs. After you turn on the Enable logging toggle, the application will record logs for 30 minutes. You can monitor the remaining logging time by checking the countdown next to the toggle. +### Response headers -After 30 minutes, logging will stop, and the application will revert to its default no-logging state. To start logging, enable the toggle again. +Use response headers to add CORS, cache-control, security, or custom headers to every application response.
-You can filter log data according to the following criteria: + -- **Timestamp**. Choose the date and time when the logs have been recorded. By default, the table displays data for the past hour. +To add a header, click **Add response header**, enter the header name in the **Key** field and the value in the **Value** field, then click **Save changes**.
-- **Client IP address**. View logs collected for a particular IP. +### Environment variables -- **Edge name**. Search within the **Logs** column. +Environment variables pass configuration values to the application at runtime. Each variable can store up to 64 KB of data; for larger values, define the parameter here and read it from code through the [dictionary](#dictionary) using the same key name.
-## Response Headers + -On the **Response Headers** tab, you can update or enhance the functionality of your application by adding or modifying HTTP response headers. +To add a variable, click **Add environment variable**, enter the variable name in the **Key** field and its value in the **Value** field, then click **Save changes**.
-These Response Headers will be added to every response. For example, you may include CORS (cross-origin resource sharing) headers in each response to ensure secure communication between origins. +Access environment variables in code using the [JavaScript SDK](https://g-core.github.io/FastEdge-sdk-js/reference/fastedge/env/) or standard Rust `std::env::var("KEY_NAME")`.
- -  - +### Secrets -## Environment Variables +Use environment variables for ordinary configuration values. When a value is sensitive — an API key, access token, or password — store it as a secret instead.
-On the **Environment Variables** tab, you can update or enhance the functionality of your application by adding or modifying environment variables. +Secrets let an application access sensitive values without storing them directly in its configuration. Each secret is stored in [Secrets Manager](/fastedge/secrets-manager/manage-secrets) and linked to the application under a local key name that the code uses to retrieve the value at runtime.
-For example, the following screenshots illustrate the configuration for a geo-location application. Environment variables are set based on the geo-IP of the client making the request. With this configuration, users will view different versions of a website based on their location. + - -  - +To link a secret:
-Access the secret in code using `secret::get("KEY_NAME")` in the [Rust SDK](https://docs.rs/fastedge/latest/fastedge/secret/index.html), or [`getSecret`](https://g-core.github.io/FastEdge-sdk-js/reference/fastedge/secret/get-secret/) in the JavaScript SDK.
- -  - +### Edge Storage -Providing a secret to your application: +Edge Storage provides a shared key-value store that applications can read and update at runtime. Link a store under a local key name, and the code uses that name to open and query it.
-You define a name for the secret within the application and then select a secret from [Secrets Manager](/fastedge/secrets-manager/manage-secrets), linking it to the application. + -- **ACCESS_KEY** - name as defined in the application. -- **S3_ACCESS_TOKEN_BINARY_DUMP** - secret that is linked to the application. +To link a store:
-To access the secret within the application, use secret::get("ACCESS_KEY"), where ACCESS_KEY is the secret name defined in the application. +1. Click **Add Edge Storage**. -Access the store in code using `Store::open("KEY_NAME")` in the [Rust SDK](https://docs.rs/fastedge/latest/fastedge/key_value/struct.Store.html), or [`open`](https://g-core.github.io/FastEdge-sdk-js/reference/fastedge/kv/open/) in the JavaScript SDK.
-On the **Edge Storage** tab, you can update or enhance the functionality of your application by adding or modifying edge storage. +### Dictionary - -  - +The dictionary gives application code read-only access to edge node metadata that FastEdge populates automatically on every node, and to application parameters that exceed the 64 KB environment variable limit.
-Providing Edge Storage to your application: +**Edge node metadata** -You define a name for the store within the application and then select an edge store from [Edge Storage](/fastedge/kv-stores/manage-kv-store), linking it to the application. +FastEdge automatically populates the following keys on every edge node. These values reflect the physical node handling each request:
-- **BLACKLIST** - name as defined in the application. -- **KNOWN_BAD_IP_ADDRESSES** - storage that is linked to the application. +| Key | Description | +|-----|-------------| +| `hostname` | Hostname of the edge node | +| `env` | Deployment environment: `prod` or `preprod` | +| `role` | Node role: `edge` or `shield` | +| `region` | Geographic region of the edge node: `africa`, `asia`, `au`, `cis`, `eu`, `latam`, `me`, `na`. Additional values may be returned for reseller networks. | +| `country` | Full name of the country where the node is located | +| `country2char` | ISO 3166-1 alpha-2 country code | +| `city` | City where the node is located | +| `dc` | Point of Presence (PoP) identifier | +| `ipv4_addr_ip` | IPv4 address of the edge node | +| `ipv6_addr_ip` | IPv6 address of the edge node | +| `ipv6_enabled` | Whether IPv6 is enabled on the node: `true` or `false` | -To access the storage within the application you would use `Store::open("BLACKLIST")` as this is the name as defined within the application. +Built-in keys take priority over application parameters with the same name. To avoid unexpected behavior, don't use built-in key names as environment variable names.
-Standard environment variable access is limited to 64 KB per value. For parameters that exceed this limit, define them on the **Environment variables** tab and read them through the dictionary using the same key name.
-In Rust, use the [`dictionary` module](https://docs.rs/fastedge/latest/fastedge/dictionary/index.html):
+ +```rust +use fastedge::dictionary; + +if let Some(value) = dictionary::get("country") { + // use value +} +``` + +In JavaScript, dictionary values are exposed through `getEnv()` from the [`fastedge::env`](https://g-core.github.io/FastEdge-sdk-js/reference/fastedge/env/) module:
+ +```js +import { getEnv } from 'fastedge::env'; + +const country = getEnv('country'); +``` + +All management operations use the https://api.gcore.com/fastedge/v1/apps/{id} endpoint, where `id` is the numeric application identifier returned by GET /fastedge/v1/apps.
All requests authenticate with an [API token](/account-settings/api-tokens). Set it as an environment variable before running the examples:
+ +```bash +export GCORE_API_KEY="{YOUR_API_KEY}" +``` + +## Application lifecycle + +To retrieve the current application state, including its configuration fields and binary ID:
+ +```bash +curl -X GET "https://api.gcore.com/fastedge/v1/apps/APP_ID" \ + -H "Authorization: APIKey $GCORE_API_KEY" +``` + +The response includes all fields needed for subsequent PUT requests: `id`, `binary`, `name`, `status`, `rsp_headers`, `env`, `secrets`, and `stores`.
+ +To stop the application, send a PUT request with `"status": 0`. To start it again, use `"status": 1`. The PUT body must include all current field values — use the GET response as the base and update only the fields that change.
+ +```bash +curl -X PUT "https://api.gcore.com/fastedge/v1/apps/APP_ID" \ + -H "Authorization: APIKey $GCORE_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "id": APP_ID, + "binary": BINARY_ID, + "name": "app-name", + "status": 0 + }' +``` + +To delete the application permanently:
+ +```bash +curl -X DELETE "https://api.gcore.com/fastedge/v1/apps/APP_ID" \ + -H "Authorization: APIKey $GCORE_API_KEY" +``` + +## Metrics + +Response Status and Runtime Duration are exposed through separate endpoints. **Response Status** groups completed requests by HTTP status code; **Runtime Duration** shows execution time per request in milliseconds. Both accept the same time-range parameters.
+ +```bash +# Response status counts +curl "https://api.gcore.com/fastedge/v1/stats/calls?from=2026-06-17T00:00:00Z&to=2026-06-17T23:59:59Z&step=3600&id=APP_ID" \ + -H "Authorization: APIKey $GCORE_API_KEY" + +# Runtime duration +curl "https://api.gcore.com/fastedge/v1/stats/app_duration?from=2026-06-17T00:00:00Z&to=2026-06-17T23:59:59Z&step=3600&id=APP_ID" \ + -H "Authorization: APIKey $GCORE_API_KEY" +``` + +The `step` parameter specifies the aggregation interval in seconds. The `from` and `to` parameters use ISO 8601 UTC format.
+ +## Logs + +Logging is disabled by default and runs for 30 minutes after being enabled, then turns off automatically. Enable it by setting `"debug": true` in a PUT request.
+ +```bash +curl -X PUT "https://api.gcore.com/fastedge/v1/apps/APP_ID" \ + -H "Authorization: APIKey $GCORE_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "id": APP_ID, + "binary": BINARY_ID, + "name": "app-name", + "status": 1, + "debug": true + }' +``` + +The response includes a `debug_until` field with the UTC timestamp when logging will stop. To read log entries:
+ +```bash +curl "https://api.gcore.com/fastedge/v1/apps/APP_ID/logs?from=2026-06-17T00:00:00Z&to=2026-06-17T23:59:59Z&offset=0&limit=50" \ + -H "Authorization: APIKey $GCORE_API_KEY" +``` + +## Application configuration + +Response headers, environment variables, secrets, and Edge Storage are all updated with a single PUT /fastedge/v1/apps/{id} request. The body replaces the entire configuration — fields omitted from the request are cleared. Read the current state with GET first and use it as the base.
Set headers in the `rsp_headers` object:
+ +```json +"rsp_headers": { + "Access-Control-Allow-Origin": "*", + "Cache-Control": "public, max-age=3600" +} +``` + +**Environment variables** + +Set variables in the `env` object:
+ +```json +"env": { + "API_BASE_URL": "https://api.example.com", + "MAX_RETRIES": "3" +} +``` + +**Secrets** + +To link a secret, get its numeric ID from GET /fastedge/v1/secrets, then reference it in the `secrets` object:
To link a key-value store, get its numeric ID from GET /fastedge/v1/kv, then reference it in the `stores` object:
The following example updates all four configuration areas in one request:
+ +```bash +curl -X PUT "https://api.gcore.com/fastedge/v1/apps/APP_ID" \ + -H "Authorization: APIKey $GCORE_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "id": APP_ID, + "binary": BINARY_ID, + "name": "app-name", + "status": 1, + "rsp_headers": { + "Access-Control-Allow-Origin": "*" + }, + "env": { + "API_BASE_URL": "https://api.example.com" + }, + "secrets": { + "MY_API_KEY": {"id": 636} + }, + "stores": { + "MY_STORE": {"id": 126} + } + }' +``` + + +## Runtime data + +### Dictionary + +The dictionary is populated automatically by FastEdge on every edge node and is not configurable through the API. Access it from application code using the SDK — see the Customer Portal tab for the full key reference and code examples.
+ +README
... +``` + +Opening the URL directly in a browser shows the rendered page. If the source file does not exist at the constructed URL, the application returns the upstream HTTP error code. + +To verify the source URL the application constructs, confirm that `BASE` + path returns HTTP 200 directly before deploying. + +All requests authenticate with an [API token](/account-settings/api-tokens). Set it as an environment variable before running the examples:
+ +```bash +export GCORE_API_KEY="{YOUR_API_KEY}" +``` + +## Create a secret + +```bash +curl -X POST https://api.gcore.com/fastedge/v1/secrets \ + -H "Authorization: APIKey $GCORE_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "my-app-secret", + "comment": "API key for external service", + "secret_slots": [ + { + "slot": 0, + "value": "your-secret-value" + } + ] + }' +``` + +The response returns the created secret with its assigned ID: + +```json +{ + "id": 638, + "name": "my-app-secret", + "comment": "API key for external service", + "secret_slots": [ + { + "slot": 0, + "checksum": "03a0986e7619f1d45d12369a1a58d2bbfc3e9f8aea9c5fe84b86087ff8941abb" + } + ] +} +``` + +The `checksum` field identifies the stored encrypted value. The original value is never returned. + +## List secrets + +```bash +curl https://api.gcore.com/fastedge/v1/secrets \ + -H "Authorization: APIKey $GCORE_API_KEY" +``` + +Optional query parameters: + +| Parameter | Type | Description | +|-----------|------|-------------| +| `app_id` | integer | Filter secrets assigned to the specified application | +| `secret_name` | string | Filter by exact secret name | + +Response: + +```json +{ + "count": 2, + "secrets": [ + { + "id": 636, + "name": "docs-audit-secret", + "comment": "", + "app_count": 0 + }, + { + "id": 638, + "name": "my-app-secret", + "comment": "API key for external service", + "app_count": 1 + } + ] +} +``` + +## Get a secret + +```bash +curl https://api.gcore.com/fastedge/v1/secrets/SECRET_ID \ + -H "Authorization: APIKey $GCORE_API_KEY" +``` + +Response includes the slot list with checksums: + +```json +{ + "name": "my-app-secret", + "comment": "API key for external service", + "app_count": 1, + "secret_slots": [ + { + "slot": 0, + "checksum": "03a0986e7619f1d45d12369a1a58d2bbfc3e9f8aea9c5fe84b86087ff8941abb" + } + ] +} +``` + +## Update a secret + +Use `PATCH` to update the name, description, or slot values. Only the fields included in the request body are changed. + +```bash +curl -X PATCH https://api.gcore.com/fastedge/v1/secrets/SECRET_ID \ + -H "Authorization: APIKey $GCORE_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "comment": "Updated description", + "secret_slots": [ + { + "slot": 0, + "value": "new-secret-value" + } + ] + }' +``` + +The response returns the full updated secret object, including the new checksum for the updated slot. + +## Delete a secret + +```bash +curl -X DELETE "https://api.gcore.com/fastedge/v1/secrets/SECRET_ID?force=true" \ + -H "Authorization: APIKey $GCORE_API_KEY" +``` + +A successful response returns HTTP 204 with no body. -In order to use Secrets in an application it must first be linked to the application. See [Managing Applications - Secrets](/fastedge/manage-apps#secrets) +All requests authenticate with an [API token](/account-settings/api-tokens). Set it as an environment variable before running the examples:
-Validating a token against a specific version of a secret using timestamps: +```bash +export GCORE_API_KEY="{YOUR_API_KEY}" +``` - -  - +## Create a secret with multiple slots + +Pass all slots in a single request to create a pre-configured rotation setup: + +```bash +curl -X POST https://api.gcore.com/fastedge/v1/secrets \ + -H "Authorization: APIKey $GCORE_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "token-secret", + "comment": "Password for token validation", + "secret_slots": [ + {"slot": 0, "value": "original_password"}, + {"slot": 1741790697, "value": "new_password"} + ] + }' +``` + +## Add a rotation slot + +To add a new slot to an existing secret without removing the current ones, use `PATCH` with only the new slot: + +```bash +curl -X PATCH https://api.gcore.com/fastedge/v1/secrets/SECRET_ID \ + -H "Authorization: APIKey $GCORE_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "secret_slots": [ + {"slot": 1741790697, "value": "new_password"} + ] + }' +``` + +`PATCH` adds or updates only the slots listed in the request — existing slots at other indices are preserved. + +
-
- 4. Choose your application from the dropdown.
-
-
- 
-
- 5. (Optional) **Select the Interrupt request processing in case of error** checkbox.
-
-
-
- 9. Choose your application from the dropdown.
-
-
-
-
- 10. (Optional) **Select the Interrupt request processing in case of error** checkbox.
-
-
- 
-
-