<commit_before>Policy Language Design
======================
Designing languages is hard, so it's a good idea to get started early.
This is a living proposal for the policy language.  It may or may not reflect
the actual implementation at any given point in time.

## Syntax
Currently, the policy language is a simplified Lisp.  Lisp is a good choice at
this early stage because its simplicity will allow rapid development and
experimentation.  Eventually, once the design of the language solidifies, we
will implement a more modern syntax for the language.  The Lisp will still
stick around as an intermediate language, but users won't have to deal with it
directly.

The language will cover the basic things we expect from a lisp including
arithmetic, variable binding, conditionals, etc.  We explicitly will not
support recursion thus guaranteeing that all specifications terminate.

## Atoms
```
(docker <image>)
```
Atoms represent the basic unit of computation instantiated by the policy
language.  Typically these will be containers (or kubernetes pods perhaps), but
they may also represent external services (hostnames/IPs).  They are
instantiated in the policy language by simply declaring them (along with their
basic configuration).

```
(docker ubuntu:15.10) # Boot an Ubuntu 15.10 container.
(makeList 5 (docker ubuntu)) # Boot 5 ubuntu:latest containers.
(host external.org) # Register external.org as a reachable hostname.
```

Atoms can also be used to describe administrative constructs that aren't
directly implemented in the dataplane.  Administrators for example:

```
(user github ejj) # Github user ejj
(user github melvinw) # Github user melvinw
```

As DI supports more functionality, atoms will naturally expand to implement
more concepts.

## Labels
```
(label <name> <member list>)
```
Each atom has associated with it a collection of labels that will be used in
the application data plane.  Labels apply to a set of one or more atoms and
labels -- essentially they're named sets.  Recursion is not allowed.  Labels
may not label themselves.

```
# A database is a postgres container.
(label database (docker postgres))

# These 5 apache containers make up the webTier.
(label webTier (makeList 5 (docker apache))

# A deployment consists of a database, a webTier, and a monitoring system
(label deployment (list database webTier (docker monitor)))
```

The same labelling construction will be used for authentication policy as well.

```
# ejj is a graduate student.<commit_msg>dsl: Document the SSH key atoms<commit_after>Policy Language Design
======================
Designing languages is hard, so it's a good idea to get started early.
This is a living proposal for the policy language.  It may or may not reflect
the actual implementation at any given point in time.

## Syntax
Currently, the policy language is a simplified Lisp.  Lisp is a good choice at
this early stage because its simplicity will allow rapid development and
experimentation.  Eventually, once the design of the language solidifies, we
will implement a more modern syntax for the language.  The Lisp will still
stick around as an intermediate language, but users won't have to deal with it
directly.

The language will cover the basic things we expect from a lisp including
arithmetic, variable binding, conditionals, etc.  We explicitly will not
support recursion thus guaranteeing that all specifications terminate.

## Atoms
```
(docker <image>)
```
Atoms represent the basic unit of computation instantiated by the policy
language.  Typically these will be containers (or kubernetes pods perhaps), but
they may also represent external services (hostnames/IPs).  They are
instantiated in the policy language by simply declaring them (along with their
basic configuration).

```
(docker ubuntu:15.10) # Boot an Ubuntu 15.10 container.
(makeList 5 (docker ubuntu)) # Boot 5 ubuntu:latest containers.
(host external.org) # Register external.org as a reachable hostname.
```

Atoms can also be used to describe administrative constructs that aren't
directly implemented in the dataplane.  Administrators for example:

```
(user github ejj) # Github user ejj
(user github melvinw) # Github user melvinw
```

As DI supports more functionality, atoms will naturally expand to implement
more concepts.

### SSH Keys
SSH keys are represented as atoms. Specifically, there's `(plaintextKey <key>)` and
`(githubKey <username>)`.

## Labels
```
(label <name> <member list>)
```
Each atom has associated with it a collection of labels that will be used in
the application data plane.  Labels apply to a set of one or more atoms and
labels -- essentially they're named sets.  Recursion is not allowed.  Labels
may not label themselves.

```
# A database is a postgres container.
(label database (docker postgres))

# These 5 apache containers make up the webTier.
(label webTier (makeList 5 (docker apache))

# A deployment consists of a database, a webTier, and a monitoring system
(label deployment (list database webTier (docker monitor)))
```

The same labelling construction will be used for authentication policy as well.

```
# ejj is a graduate student.
{'fraction_non_alphanumeric': 0.06868451688009314, 'fraction_numerical': 0.004656577415599534, 'mean_word_length': 4.72142064372919, 'pattern_counts': {'":': 0, '<': 11, '<?xml version=': 0, '>': 11, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1111551', 'n_tokens_mistral': 1389, 'n_tokens_neox': 1263, 'n_words': 735}