How packages, connections, capabilities and services fit together

Here is an app calling one outside API, with nothing left out: it books a collection with a courier. Acme Couriers publishes no package, so the app describes its API itself, in shared/providers/. With an installed package, jadpo package add brings these package files and you write only the connection, the setting and the action.

The connection goes in app.jadpo. connections: and its keys are built in, couriers is your name for it, AcmeCouriers.v1 is the package below, and shipping is the domain whose actions may call it.

app.jadpo:

application {    connections: {        couriers: {            package: AcmeCouriers.v1            domains: [shipping]            credential: config.couriers_api_key            environment: config.couriers_environment        }    }}

The secret and which of the courier's hosts to use are settings. ProviderEnvironment is built in, and is .sandbox or .live.

config.jadpo:

config {    couriers_api_key: Text {        secret: true    }    couriers_environment: ProviderEnvironment {        default: ProviderEnvironment.sandbox    }}

The package names itself and says how the API is reached.

shared/providers/acme_couriers/v1/package.jadpo:

/// Acme Couriers' booking API, written from its documentation.package AcmeCouriers.v1 {    licence: Licence.proprietary    jadpo: "1.0"}

licence: is required, and Licence.proprietary suits a package only your app uses. jadpo: is also required: it is the lowest Jadpo version the package says it needs, a major and minor number as text. Jadpo checks only that form and compares the number with nothing yet, so "1.0" passes on every release, even one before 1.0.

shared/providers/acme_couriers/v1/provider.jadpo:

/// Acme Couriers' booking API.provider {    protocol: Protocol.json_http    hosts: {        live: "https://api.acme-couriers.example"        sandbox: "https://sandbox.acme-couriers.example"    }    credential: CredentialScheme.bearer}

A resource is a group of the API's operations. This one has one operation, which takes a CreateBooking and answers with a Booking, two types the package declares. changes: true says the call changes something at the courier. idempotent: true says the call is safe to send again, here because repeating it books one collection, so Jadpo may retry it. source: PackageSource.written tells whoever reviews the package that a person wrote this operation from the courier's documentation, rather than importing it (Provenance and confirmation).

shared/providers/acme_couriers/v1/resources/bookings.jadpo:

public resource bookings {    create: {        method: HttpMethod.post        path: "/v1/bookings"        input: CreateBooking        output: Booking        changes: true        idempotent: true        source: PackageSource.written    }}

shared/providers/acme_couriers/v1/types/create_booking.jadpo:

/// What booking a collection takes.public type CreateBooking = Object {    postcode: Text}

shared/providers/acme_couriers/v1/types/booking.jadpo:

/// A booked collection.public type Booking = Object {    id: Text}

The action calls the operation through the connection. use app brings in the connection, and use shared/providers/acme_couriers brings in the package, whose public names are written AcmeCouriers.<name>.

domains/shipping/actions/book.jadpo:

use app { couriers }use shared/providers/acme_couriers/// Books a collection with the courier, through its connection.action book(request: AcmeCouriers.CreateBooking) -> AcmeCouriers.Booking {    return couriers.bookings.create(request)}

Run jadpo records update once, which writes down the hosts the app can reach, then check the project:

jadpo check

Not yet confirmed  Record each with `jadpo package record`, which checks a sandbox answer  against its types (agent)    couriers.bookings.createchecked: 1 unconfirmed, 8 files

The check passes. "Not yet confirmed" means no real answer from the courier has been checked against the types you wrote, so they are only as right as what you read. It doesn't fail the check, and jadpo approval shows a person what ships unconfirmed. To confirm the call, put a sandbox key in .env.local and run jadpo package record couriers bookings.create --input '{"postcode": "M1 1AA"}', which calls the sandbox once, checks the answer and keeps it as a recording in the package (Provenance and confirmation).

A database and mail are connections too. They use a driver built into Jadpo, so there is no package to write. email: says which connection sends the app's email, whichever provider it is, which makes email a capability.

app.jadpo:

application {    connections: {        main: {            driver: Driver.postgres            url: config.database_url        }        mail: {            driver: Driver.smtp            host: config.smtp_host            credential: {                username: config.smtp_username                password: config.smtp_password            }        }    }    email: {        connection: mail        from: config.mail_sender    }}

config.jadpo:

config {    database_url: PostgresUrl    mail_sender: Email    smtp_host: Hostname    smtp_password: Text {        secret: true    }    smtp_username: Text}

What each one is

A service run by Jadpo is a seventh term, for a thing that isn't built yet: Running a service in a container.

Two words that mean two things

runs: is one key with two jobs, depending on where it is written:

"Service" has two meanings too. A built-in service, such as feature flags, is part of Jadpo's runtime, inside the app's process. A service run by Jadpo would be a container beside it, and isn't built yet.

How they relate

the app's process: jadpo dev's interpreter, or a native or Workers deployable│├── domain code ── calls ──► library package             pure functions, in process│├── domain code ── calls ──► connection: provider package ── HTTPS ──► provider's API│                                                    on the internet (hosts:), or at host:│└── built-in services: flags, rate limits, email, files, search, ...       │ outside work goes through a capability       └──► capability: email, files, database, ai, ...              filled by one connection, either              ├── a built-in driver ──────────── its protocol ──► a server the operator runs:              │                                                  PostgreSQL, SMTP              └── a provider package's provides/ ── HTTPS ──────► provider's API:                                                                 Resend

• Code calls a provider's operations only through a connection, from an action in a domain the connection lists: couriers.bookings.create(...) (Calling).
• Code never names what fills a capability. It writes an EmailMessage type or a File field, and app.jadpo picks the connection, so changing provider changes app.jadpo and its settings, never domain code.
• One provider package can be both. Resend's fills email through provides/email.jadpo, and the domains its connection lists can call its own operation, emails.send, as any provider's.
• Packages fill capabilities and never invent them, never bring a driver and never depend on another package.
• Anything that keeps data is the operator's. PostgreSQL and an SMTP server are reached through a driver at the address a setting gives; Jadpo never runs them. The operator may run them in Docker or anywhere else, and the app sees only the address.

Where each runs

jadpo check refuses a deployable whose target can't run a connection it reaches, naming what to use instead: on Workers the disk and SMTP on port 25 (Capabilities, "Targets").

An app needs no Docker or Podman to be checked, tested, run in jadpo dev or built. The disposable PostgreSQL comes from the machine's own PostgreSQL tools, a native deployable is one binary (A native deployable) and a Workers deployable is a Worker. Neither is an image.

What is built of these

Of what this page describes, these aren't built yet: running a service in a container; the Redis and S3 drivers; OAuth grants; the cache, publishing, documents, bot_check and scanning capabilities; an outside engine for search; the hosted registry; importers other than openapi; and choosing a provider when deploying.

Of the built-in services, flags, rate limits, files, audit and search are partly built, email is built, and documents, bot protection and the telemetry: section aren't built yet. Each page's "What is built" table is the record: this page's What is built and Built-in services'.