# How connections to packages are read

This is the detail behind [Connecting in `app.jadpo`](connecting-in-app-jadpo.md):
which keys a connection to a package takes and needs, and what
`jadpo check` writes about the hosts it reaches.

- **Naming the package.** `package:` names a provider package the app
  holds, installed or its own, by its name and version
  (`AcmeCouriers.v1`), as the lock does; `app.jadpo` needs no `use` line
  for it. A version the app doesn't hold names the ones it does; a library
  package is refused, since it needs no connection
  (`connection.package_unknown`).
- **The keys.** A connection to a package takes `package:`, `domains:`,
  `credential:`, `environment:`, `host:`, `timeout:`, `retry:`,
  `max_concurrent:`, `webhooks:`, `erasure:`, `development:`, `polls:`
  and `outbound:`, and each setting its package declares; anything else is
  `connection.key_invalid`, with the nearest key. Each is read where it
  `connection.key_invalid`, with the nearest key. Each is read where it
  is used. Driver connections keep their own keys.
- **What a package needs.** `domains:` always, a list of the app's
  domains by name, each once and at least one.
  `credential:` exactly when `provider.jadpo` names a `credential:`
  scheme, read from a `secret: true` setting. `environment:` exactly when
  the package has `hosts:`, read from a `ProviderEnvironment` setting, the
  new built-in enum (`.sandbox`, `.live`); a value written in source is
  refused, so each deployment says which it calls. `host:` exactly when
  the package has neither `hosts:` nor `runs:`, read from a `Url` setting
  (or a type built on it); beside `runs:` it may be given, and beside
  `hosts:` it is refused. A missing one is `connection.key_missing`, a
  value of the wrong kind `connection.value_invalid`, a key the package
  doesn't take `connection.key_invalid`. That a host is HTTPS is checked
  when calls go out, since a `Url` setting may hold
  `http://`.
- **A package's settings.** `provider.jadpo`'s `settings:` names each
  setting and its type, one of `Text`, `Int`, `Decimal`, `Bool` and
  `Duration` (`package.provider_invalid` otherwise), and every connection
  gives each, written out or read from a setting whose type is built on
  it. A setting has no default: every connection gives each one.
- **The network report.** `build/report/network.md` and `.json`, written
  by `jadpo check` once the connections and their addresses read cleanly,
  designed with the CLI design language's calm, plain rules: a title, one
  sentence, and one table row per host in order of connection and host,
  with no times or totals, so a change is a one-line diff. A package's
  live and sandbox hosts each get a row, `when` its environment setting
  says so; a package with no fixed host is listed at the address in its
  `host:` setting; a package Jadpo runs, as the service it runs from its
  image. Database and cache connections are listed at their `url:`
  setting, for the domains whose entities they store; the disk driver
  reaches no host and isn't listed. The JSON gives each host's
  `connection`, `address`, `setting` or `service`, `when`, `for` and
  `domains`. The manifest has a `host` node for each row, under its
  connection, and the graph's diff says which changes to them need a
  person ([Package upgrades](package-upgrades.md)).
- **How the seam finds a connection's driver.** The capability seam
  asks the host for `capability(connection)`; a host gives a driver only
  for a connection whose declared driver it carries. Natively and in
  `jadpo dev` that is the disk driver for the stores of files the running
  program's plan lists (re-read after every reload); in `jadpo test` the
  in-memory store for the same list, which the executor gives the test's
  host. A package's connection is given the package driver ("How provider
  calls are made"), or in `jadpo dev` and `jadpo test` the package's fake
  ("Fakes and the development call log").

> `outbound:` waits for services, which aren't built yet. Package
> settings have no defaults yet. The approval report that shows host
> changes isn't built yet.