# Advanced data and networking

[Programming guides](README.md) · [Editions](editions.md)

Creator Pro and its technical trial support SQLite, selected files and directories, broader HTTPS requests, streaming, WebSockets and separate development/test/production configuration. These APIs work in the desktop IDE, CLI and supported generated native applications. The public playground cannot run them; browser and phone hosts have no advanced application adapter.

Learner still includes [saved values](storage.md), [bounded HTTPS GET](../builtins/getWebText.md) and basic forms through code. Using a Pro visual editor does not turn its ordinary Core output into a Pro-only program.

## Declare what the program needs

There are three separate decisions: the IDE/CLI verifies Pro for an advanced run/build, the project declares its requirements, and the person running the program explicitly grants access. A licence alone never grants files or network access.

In **File → Project web access**, use **Data and integrations · Creator Pro**. Requirements remain editable in Learner. A portable project's `capabilities` value can be:

```json
{
  "schemaVersion": 2,
  "httpsOrigins": ["https://api.example.com"],
  "advanced": {
    "sqlite": true,
    "files": ["input"],
    "directories": ["reports"],
    "httpMethods": ["GET", "POST"],
    "streaming": true,
    "webSockets": true,
    "configKeys": ["region"],
    "secretNames": ["api"]
  }
}
```

This is one property of a project manifest, not a complete project. Include only requirements you use. Version 1 declarations remain supported. Slot names are portable names, not host paths; do not put credentials or licence flags here.

Before a run, permissions start unchecked. Select files, directories, configuration and permitted origins explicitly. Each writable scope needs a separate choice. **Run without access** still runs the program, but denied operations return a result with `ok: false`. Stop, permission revocation and replacement of the project close active connections and handles.

## Check every result

All these APIs return an ordinary Map:

| Key | Meaning |
|---|---|
| `ok` | Whether the operation succeeded |
| `status` | HTTP status, or zero for other operations |
| `value` | JSON-compatible result, or None |
| `error` | Stable error text; empty on success |

Check `ok` before using `value`. Common failures include `denied`, `unavailable`, `invalid`, `limit`, `cancelled` and `timeout`. An unsupported host reports `unavailable`. Errors do not expose credentials, SQL text or host paths.

Examples below are for a desktop project with the matching declarations and explicit permissions. They are not public-playground examples.

## Use SQLite

A project with a stable app identity gets a private database. Source code never chooses a database path. Use parameters for values and migrations for schema changes:

```text
# language: en
let schema = migrateData(1, ["CREATE TABLE scores (name TEXT NOT NULL, points INTEGER NOT NULL)", "CREATE INDEX scores_points ON scores(points)"])
if schema["ok"]:
    let saved = executeSQL("INSERT INTO scores(name, points) VALUES (?, ?)", ["Nova", 12])
    if saved["ok"]:
        let rows = querySQL("SELECT name, points FROM scores ORDER BY points DESC LIMIT 10", [])
        if rows["ok"]:
            say rows["value"]
        else:
            say rows["error"]
    else:
        say saved["error"]
else:
    say schema["error"]
```

[executeSQL](../builtins/executeSQL.md) returns the changed-row count; [querySQL](../builtins/querySQL.md) returns a list of maps. Give result columns unique names. SQLite NULL becomes None; BLOB values and integers outside the exact 53-bit range are unsupported.

Use [beginTransaction](../builtins/beginTransaction.md), [commitTransaction](../builtins/commitTransaction.md) and [rollbackTransaction](../builtins/rollbackTransaction.md) for transactions. An unfinished transaction rolls back when its host closes.

Migrations start at 1 and proceed sequentially. Repeating an applied version with identical steps succeeds without reapplying; changing its steps fails. Steps and their checksum commit together. A migration cannot run inside an open transaction.

Bounds include 32 MiB database pages, 16 KiB per SQL statement, 128 parameters/columns, 1000 result rows, 1 MiB values/results and a 5-second operation timeout. A migration permits 64 steps and 64 KiB total SQL. Raw SQL transaction commands, PRAGMA, ATTACH, extensions, triggers, virtual tables and internal `_pliro_` tables are denied.

## Read selected files

[readFileText](../builtins/readFileText.md) and [writeFileText](../builtins/writeFileText.md) take a declared slot and a relative path. For a selected-file slot, the relative path must be empty:

```text
# language: en
let contents = readFileText("input", "")
if contents["ok"]:
    say contents["value"]
else:
    say contents["error"]
```

For a directory slot, use paths such as `report.txt` or `reports/day1.txt`. [listDirectory](../builtins/listDirectory.md) with an empty path lists the selected directory. Paths cannot escape its root; absolute paths, drive names and backslashes are rejected.

Reads and writes use UTF-8 and allow at most 1 MiB. Lists contain at most 256 sorted entry names. Read-only is the default; writing requires a separate grant. A writable directory can create regular files within its scope. Writes replace and sync file contents; they are not crash-atomic backups.

## Make an HTTPS request

[httpRequest](../builtins/httpRequest.md) supports declared GET, HEAD, POST, PUT, PATCH, DELETE and OPTIONS methods. Even its GET operation is an advanced API; Learner uses `getWebText` or `getWebJSON`.

```text
# language: en
let reply = httpRequest("https://api.example.com/items", {"method": "POST", "body": "{\"name\":\"Nova\"}", "format": "json", "headers": {"Content-Type": "application/json"}, "authorizationSecret": "api"})
if reply["ok"]:
    say reply["value"]
else:
    say reply["status"], reply["error"]
```

Replace the example origin with your service in both source and project settings. Options are `method`, text `body`, `format` (`text` or `json`), `headers` and `authorizationSecret`. Allowed headers are X-* plus Accept, Content-Type, If-Match, If-None-Match and Idempotency-Key. Direct Cookie/Authorization headers are denied; authentication uses a host-selected secret name.

Origins must be declared and explicitly granted. TLS checks, public-address validation, rate/concurrency limits and cancellation remain active. Private, loopback, link-local and metadata destinations are denied. Requests use no ambient credentials or proxy and follow no redirects. Non-2xx results expose status, not the response body.

Limits are 10 seconds per request, 1 MiB for bodies/text results, 64 KiB for JSON results and 16 KiB for headers.

## Stream and use WebSockets

[openHTTPStream](../builtins/openHTTPStream.md) opens a GET-only HTTPS response and returns an opaque handle. [readHTTPStream](../builtins/readHTTPStream.md) returns `{"text": ..., "done": ...}` in `value`, one UTF-8 line including its newline. Close it with [closeHTTPStream](../builtins/closeHTTPStream.md). Limits are 32 KiB per line, 1 MiB total and two minutes.

[openWebSocket](../builtins/openWebSocket.md) accepts `wss://` only; declare and grant its corresponding `https://` origin. [sendWebSocket](../builtins/sendWebSocket.md) and [receiveWebSocket](../builtins/receiveWebSocket.md) exchange text. [closeWebSocket](../builtins/closeWebSocket.md) releases the handle. Authentication uses the same host-secret rules.

WebSockets allow 64 KiB per message, 256 messages and 1 MiB combined traffic, 10 seconds per message and two minutes per connection. Compression is disabled. A host permits one open stream/socket; closed handles cannot be reused.

## Choose configuration and secrets on the host

The runner selects a separate host JSON file, outside project source/assets:

```json
{
  "schemaVersion": 1,
  "environments": {
    "development": {
      "values": {"region": "eu"},
      "secrets": {
        "api": {
          "value": "Bearer replace-on-the-host",
          "origins": ["https://api.example.com"]
        }
      }
    },
    "test": {"values": {"region": "test"}, "secrets": {}},
    "production": {"values": {"region": "eu"}, "secrets": {}}
  }
}
```

[configValue](../builtins/configValue.md) reads a declared key. [configEnvironment](../builtins/configEnvironment.md) returns `development`, `test` or `production`; the default is `development`. Each environment permits 32 values and 32 secrets. Host JSON is limited to 64 KiB.

The language cannot read secret values. The host inserts the named secret into Authorization only for its permitted origin. This is explicit host-file configuration, not an encrypted keychain or hosted vault. No process-environment variables are read implicitly.

## CLI and generated applications

Flags precede the project path:

```sh
pliro run --allow-database --allow-advanced-network --allow-https https://api.example.com --select-file input=/chosen/input.txt --writable-directory reports=/chosen/reports --configuration /private/config.json --environment test example.bipli
```

`--select-directory` and `--writable-file` are also available. The debugger and profiler accept the same permissions.

Supported native exports include the advanced runtime and require Go 1.25 or newer when building. A generated app contains no Pliro product-licence check. Its user supplies advanced permissions at launch:

```sh
my-app --pliro-permissions /private/permissions.json
```

```json
{
  "schemaVersion": 1,
  "grants": {
    "sqlite": true,
    "network": true,
    "httpsOrigins": ["https://api.example.com"],
    "files": {"input": {"path": "/chosen/input.txt", "write": false}},
    "directories": {"reports": {"path": "/chosen/reports", "write": true}},
    "environment": "production"
  },
  "configurationPath": "/private/config.json"
}
```

Use paths appropriate to the user's machine. This host file is not bundled into the export. Without it, no advanced access is granted. Graphical native apps currently use this launch file too; an advanced graphical permission picker is not available. Core HTTPS GET retains its separate `--pliro-allow-https` or graphical consent when used alongside advanced APIs. `--pliro-third-party-notices` prints bundled dependency licences.

[Development tools](development-tools.md) · [Build and export](build.md) · [Built-in reference](../builtins/README.md)