rfc-snappy-ports.md

The current situation

The current spec states that ports are a top level entry in the package.yaml as

    name: go-example-webserver
    vendor: Alexander Sack <[email protected]>
    architecture: amd64
    icon: meta/go.svg
    version: 1.0.1
    services:
     - name: webserver
       description: "snappy example: golang mini webserver"
       start: ./go-example-webserver
    ports:
       required: 80

Critique

The ports declaration in it's current form gives only an indication that somewhere in this package the port is used. It is not known if it used by a service, a web front or a short lived binary.

Proposal

The proposal, aligned to certain security features that are bound to happen, is to make ports part of the service or binary that wants to use them. Additionally, the description of their intended purpose to be more clear.

What this means is that ports are:

• bound to a service (or binary).
• have an associated protocol.
• tagged in such a way that other components can use them.

With these requirements in mind, the package.yaml would look like:

    name: foo
    description: description for foo
    version: 1.0.1
    services:
        - name: webserver
          description:  description of webserver
          start: bin/webserver
          ports:
               internal: 
                   localcomm1:
                       port: 3306/tcp
                       negotiable: yes
               external:
                   ui:
                       port: 8080/tcp 
                       negotiable: no

In this description, the port tags are:

• localcomm1: which can be used for local communication within the application.
• ui: this is a special key which will also be picked up by the webdm.

Tags are free form, but some can gain special use, such as an external/ui one which would be picked up by the webdm and used to open the application through the web.

There's also a new key, negotiable, which means that if the intended port is in conflict as it has been used by another package it will allow for it to be bound to another port (there is no implementation for this yet).

Multiple ports, ranges of ports

Multiple lists of ports can be separated by commas (preferably with no intervening whitespace), e.g.:

          ports:
               internal: 
                   localcomm1:
                       port: 3306,3307,3308/tcp
                       negotiable: yes
               external:
                   ui:
                       port: 80,8080/tcp 
                       negotiable: no

Ranges of ports can be defined by separating a start port and an end port with a dash (ASCII -, unicode U+002D, unicode figure dash U+2012 or unicode en-dash U+2013), e.g.:

          ports:
               internal: 
                   localcomm1:
                       port: 3306-3308/tcp
                       negotiable: yes
               external:
                   ui:
                       port: 8080-8089/tcp 
                       negotiable: no

port: 80,8080/tcp

it would be kind of hard to eyeball a mix of protocols used in this way, e.g.;

port: 80,8080/tcp,1050/udp

do you think repeating /[port] for every comma separated value could be better? e.g.;

port: 80/tcp,8080/tcp,1050/udp

For the examples completeness, I'd say, for webdm only a single port should be specified if you want to have open support.

Port ranges look good.

Thanks for your contribution btw!