# Remote execution

Currently remote execution only applies to execution of modules in container.
Theoretically it could also be used e.g. to execute modules on other machines via SCP/SSH.

## Sequence diagram overview

The following sequence diagram illustrates the remote protocol:

```mermaid
sequenceDiagram
    client ->>+ executor: StartTaskRequest
    client ->> client: listen for executor events
    executor ->> executor: Start FS watcher
    executor ->> executor: Unmarshal task and execute
    
    loop stream task output & logs
        executor -->> client: TaskLog
        executor -->> client: TaskOutput
    end

    executor -->>- client: TaskResult - as soon as execution completes
```

## Execution steps for container tasks

The overall execution looks like this:

1. create container network
1. create container
1. copy buildr binary, tools and content into container
    - if input mapping is configured, content is copied as it would be mapped
    - if no input mapping is configured complete repository is copied
1. start container with buildr as entrypoint (gRPC server)
1. connect to gRPC server
1. send `StartTaskRequest` specifying what to do - although it's called **TaskRequest** it could be any module
1. server starts a FS watcher to monitor modified files
1. buildr CLI listens for logs and output from executed task
1. as soon as the execution completes, modified files are collected into a .tar.s2 file and error message + location of the archive are sent as result to buildr CLI
1. CLI copies archive back and extracts modified files to output directory