# The .cro.yml File

## Purpose

The `.cro.yml` file is stored in the root directory of a service. It provides
some metadata about the service that is used in combination with the `cro`
development tool (both the CLI and the web version). It is intended that, if
used, the file is committed to version control.

The `.cro.yml` file is only used by the `cro` development tool. It is not
required for the correct operation of the service, and need not be included
when the service is deployed (the `.dockerignore` generated when stubbing the
service excludes it from the container).

## Basic Information

The `.cro.yml` file should be a dictionary at the top level. It must include:

* The key `cro` with a value of `1`. This will allow for versioning of the
  file as Cro evolves.
* The key `id`, followed by an ID for the service. The value may contain the
  letters A..Z and a..z, the digits 0..9, the underscore (`_`), the dash (`-`)
  and the forward slash ('/'). This will be used to identify the service when
  using the CLI (such as in `cro run service-id`).
* The key `entrypoint`, which is the Raku source file that should be run to
  start the service. It should be specified relative to the `.cro.yml` file.
  This will be used by the `cro` development tool to start the service.

It may optionally include:

* The key `name`, which provides a human-friendly name for the service. This
  will be displayed in the web UI. If not provided, the `id` will be used in
  its place.

For example:

    cro: 1
    id: flashcard-backend
    name: Flashcards Backend
    entrypoint: service.raku

## Endpoints

An endpoint is something exposed by a service for services or applications to
connect to. Most often, it's a network port. The stub services produced by Cro
do not hard-code a port number, but instead take it from an environment
variable.

Endpoints are specified as a list under the `endpoints` key. For example, a
service that accepts both HTTP and HTTPS would look as follows:

```
endpoints:
    - id: http
      name: HTTP (Insecure)
      protocol: http
      host-env: FLASHCARD_BACKEND_HTTP_HOST
      port-env: FLASHCARD_BACKEND_HTTP_PORT
    - id: https
      name: HTTP (Secure)
      protocol: https
      host-env: FLASHCARD_BACKEND_HTTPS_HOST
      port-env: FLASHCARD_BACKEND_HTTPS_PORT
```

The `id` is used to identify the endpoint in commands and when referencing it
from other services. The `name` is for display in the user interface; it is
optional and will default to the `id`. The `protocol` describes the protocol
that the endpoint speaks; this is used when stubbing code to call the service
from another service. Protocols include:

* `https` - HTTP/1.1 and/or HTTP/2.0 secure (negotiated using ALPN)
* `http` - HTTP/1.1 insecure
* `http2` - HTTP/2.0 insecure (starts HTTP/2 by prior knowledge)
* `wss` - web socket secure
* `ws` - web socket insecure
* `zeromq/rep` - ZeroMQ `REP` (generated client would be a `REQ`)
* `zeromq/pub` - ZeroMQ `PUB` (generated client would be a `SUB`)

It is allowed to write multiple protocols with a comma. This is mostly useful
when an endpoint handles both HTTP and web sockets (securely as `https,wss` or
insecurely as `http,ws`).

The `host-env` and `port-env` fields name environment variables that will be
populated with the host and port that the endpoint should be hosted on.

## Links

The `links` section describes which other Cro services this one references. It
is used for `cro run` and `cro trace` (or running/tracing the services in the
web interface) to inject environment variables indicating the host and port of
the other endpoints. The environment variables can then instead be supplied by
configuration management, Kubernetes, and so forth when deploying the service.

A `links` section might look like:

```
links:
  - service: flashcard-backend
    endpoint: https
    host-env: FLASHCARD_BACKEND_HTTPS_HOST
    port-env: FLASHCARD_BACKEND_HTTPS_PORT
  - service: users
    endpoint: https
    host-env: USERS_HTTPS_HOST
    port-env: USERS_HTTPS_PORT
```

Where `service` is the ID of the service (defined by `id` in its `.cro.yml`),
`endpoint` is the ID of the endpoint (from the target service's `.cro.yml`'s
`endpoints` section), and `env` is the environment variable specifying the
host and port in the form `host:port`.

## Environment

Services will usually need other resources, such as database connections,
addresses of non-Cro services, and (development fake) security credentials. It
may be convenient to inject these using the environment. The `env` section
provides a way to set environment variables that will be passed to the
service. This is a handy way to store development configuration and cut down
a little of the setup work needed when other developers want to get the
services running.

```
env:
  - name: FLASH_DATABASE
    value: test-database.internal:6555
  - name: JWT_SECRET
    value: my-dev-not-so-secret
```

## Controlling automatic restarts

By default, `cro run` and `cro web` will automatically restart the service
when a file changes in any directory beneath where the `.cro.yml` is located.
All hidden files and directories are ignored by default (those starting with a
`.`, for example `.precomp/` and `.git/` directories).

To add extra directories to ignore, create an `ignore` section with a list of
patterns in the `.cro.yml` file. These are processed like `.gitignore`. For
example:

```
ignore:
  - node_modules/
```