Tunnel

Tunnel is an interface to perform operations from a source directory to target directory.

Source directory can be either a local directory or a git repository.

With tunnel, you can:

  • Uncouple and automate the development setup files from your project directory
  • Improve and/or simplify CI operations
  • Create common operations and use it everywhere
  • Copy, fetch, or manage git ignored files to a project
  • Etc.

Getting started

In order to use tunnel, it is necessary to define a source directory with the command rit config tunnel add and reference it when using rit tunnel.

Hello tunnel

First, create a local directory to be your source:

mkdir source

Using your favorite text editor, create the settings file source/tunnel.yaml:

version: '0.0.1'

run: echo hello tunnel

Add the tunnel source to your configuration:

rit config tunnel add local source

The output should be:

[success] tunnel config 'source' saved

Finally, use it anywhere:

rit tunnel --config source run

The output will be:

hello tunnel

[success] tunnel successfully performed the operation

Copying files

To copy a source file to a target path, first create a file in source directory, such as source/secrets.py:

A_SECRET = 'SUCH_SECRET_MUCH_WOW'

SOME_PRODUCTION_CONTEXT_SECRET = 'SOME_PRODUCTION_CONTEXT_VALUE'

Modify your source/tunnel.yaml:

version: '0.0.1'

run:
  .hello: echo hello tunnel

  .copy:
    link_dir: ./target
    link_mode: symlink

    run: cp secrets.py target/

Finally, use it anywhere:

rit tunnel --config source run copy

The output will be:

[success] tunnel successfully performed the operation

Set default source configuration

To simplify the tunnel usage, you can set either a global or local default configuration.

A local configuration is used whenever a --config is not defined and the target path contains a default source.

A global configuration is used whenever both --config and a local configuration is not set.

Both types can be set by using rit config tunnel default set.

For example, to set a global default source configuration, use:

rit config tunnel default set source

The output will be:

[success] tunnel config 'source' set as global default

To set a local default source configuration in your current directory, use:

rit config tunnel default set source --path .

The output will be similar to:

[success] tunnel config 'source' set as default on path '/current/path'

To list all your tunnel source configurations, use:

rit config tunnel list

The output will be similar to:

# Tunnels Configs

- source: /path/to/source (local)

## Default Paths

- (global): source
- /current/path: source

Finally, you can use rit tunnel without the --config modifier:

rit tunnel run hello

Additional settings

Please check the section below to discover all the parameters and operators available to use in a YAML settings file.

Settings parameters and Settings operators

Settings parameters allows to configure how the operation will be performed.

Settings operators allows to define the operation itself.

Settings parameters

environment

Set one or more environment variables to be used by any of the children operators.

  • Pattern:
  environment:
    [<ENV_NAME>: <ENV_VALUE>]+
  • Examples:
  environment:
    NODE_ENV: production

  run: yarn build
  environment:
    PARSE_FILES: 'true'
    EXPORT_AS: json

  run: ./parser $PARSE_FILES $EXPORT_AS

input

Set one or more environment variables that can be defined by the user before performing a operation. Ensure defaults_to is set to avoid errors when executing operations without input enabled.

  • Pattern:
  input:
    [<KEY>:
      environment_name: <ENV_NAME>
      defaults_to: <ENV_VALUE>]+
  • Examples:
  input:
    NODE_ENV:
      defaults_to: production

  run: yarn build
  input:
    parse_files?:
      environment_name: PARSE_FILES
      defaults_to: 'true'
    export_as:
      environment_name: EXPORT_AS
      defaults_to: json

  run: ./parser $PARSE_FILES $EXPORT_AS

link_dir

Set the path relative to the current settings directory to fetch the files from target directories. The fetch will be performed only if both link_dir and link_mode are set.

  • Pattern:
  link_dir: <LINK_DIR>
  • Examples:
  link_dir: ./app
  link_mode: copy

  run: docker-compose up
  link_dir: ./data_source
  link_mode: symlink

  run: cp data.csv data_source/

link_mode

Set how to fetch the target at link_dir. The fetch will be performed only if both link_dir and link_mode are set.

  • Options:

    • copy: Copy the target to the tunnel directory. Use it whenever you want to ensure the state of the target directory will not change.
    • symlink: Create a symbolic link at the tunnel directory. Use it whenever you want to change the state of the target directory.
    • none (default): Do not perform any tunnel. Use it whenever you want to perform operations without the need to bind directories.
  • Pattern:

  link_mode: <copy|symlink|none>
  • Examples:
  link_dir: ./app
  link_mode: copy

  run: docker-compose up
  link_dir: ./data_source
  link_mode: symlink

  run: cp data.csv data_source/
  link_mode: none

  run: echo hello world

Settings operators

An operation can be either a command or a list of commands.

.argument

An argument operator is used to set a graph to define multiple operations. A child argument inherit all the parameters set in all its parents. A sibling argument shares the parameters from its parents and from the current context.

  • Pattern:
  .<ARG_NAME>:
    ...

    [.<CHILD_ARG_NAME>:
      ...]*

  [.<SIBLING_ARG_NAME>:
    ...]*
  • Example:
  run:
    .hello:
      run: echo hello

      .world:
        run: echo world

      .name:
        input:
          NAME:
            defaults_to: Jon
          SURNAME:
            defaults_to: Doe

        direct: echo $NAME $SURNAME

        .joana: echo Joana $SURNAME

        .snow: echo $NAME Snow
  $ rit tunnel run hello
  hello

  $ rit tunnel run hello world
  hello
  world

  $ rit tunnel run hello name
  hello
  Jon Doe

  $ rit tunnel run hello name joana
  hello
  Joana Doe

  $ rit tunnel run hello name snow
  hello
  Jon Snow

direct

An direct operator is used to set a operation that will be executed ONLY if the arguments received is exactly the same as the path to the parent argument operator. If the path continues, it will not be executed.

  • Pattern:
  direct: [<COMMAND>]+
  • Example:
  run:
    .hello:
      direct: echo hello

      .world:
        direct: echo world

      .there:
        direct:
          - echo hello there
          - echo general Kenobi!
  $ rit tunnel run hello
  hello

  $ rit tunnel run hello world
  world

  $ rit tunnel run hello there
  hello there
  general Kenobi!

redirect

An redirect operator is an special operation used to redirect the current path to another path or to another settings file. If strict option is set to true, it will execute only the command defined in the last argument set by to option.

  • Pattern:
  redirect:
    to: <INTERNAL_OR_EXTERNAL_PATH>
    external: <true|false (default)>
    strict: <true|false (default)>
  • Internal example:
  run:
    .hello:
      run: echo hello

      .world:
        run: echo world

    .hi:
      redirect:
        to: hello

    .goodbye:
      .forever: echo goodbye
      .swag: echo hasta la vista, baby
      .nvm:
        redirect:
          to: hello world
          strict: true
  $ rit tunnel run hello
  hello

  $ rit tunnel run hello world
  hello
  world

  $ rit tunnel run hi
  hello

  $ rit tunnel run hi world
  hello
  world

  $ rit tunnel run goodbye forever
  goodbye

  $ rit tunnel run goodbye swag
  hasta la vista, baby

  $ rit tunnel run goodbye nvm
  world
  • External example:
  example
  ├── tunnel.yml
  └── outsider
       └── tunnel.yml
  # example/tunnel.yml

  run:
    .hello:
      run: echo hello

      .world:
        run: echo world

      .outsider:
        redirect:
          to: outsider
          external: true
  # example/outsider/tunnel.yml

  run:
    direct: echo what?

    .ola: echo ola!
  $ rit tunnel hello
  hello

  $ rit tunnel hello world
  hello
  world

  $ rit unnel hello outsider
  hello
  what?

  $ rit tunnel hello outsider ola
  hello
  ola!

run

Run is the basic operator type and will be run whenever its path is a subset of the arguments, except on strict redirect. A root run operator must be set in each settings file, otherwise rit will fail.