https://github.com/encoredev/emissary
Emissary is a management application which runs along side your app in your cloud
https://github.com/encoredev/emissary
encore go golang
Last synced: about 1 month ago
JSON representation
Emissary is a management application which runs along side your app in your cloud
- Host: GitHub
- URL: https://github.com/encoredev/emissary
- Owner: encoredev
- License: mpl-2.0
- Created: 2022-03-11T10:47:56.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-04-19T12:26:32.000Z (about 1 year ago)
- Last Synced: 2025-04-30T21:05:57.152Z (about 1 month ago)
- Topics: encore, go, golang
- Language: Go
- Homepage: https://encore.dev
- Size: 188 KB
- Stars: 5
- Watchers: 5
- Forks: 1
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
# Emissary
When you deploy an [Encore application to your own cloud](https://encore.dev/docs/deploy/own-cloud) Emissary is deployed
alongside. It provides the Encore platform a way to access resources with your clouds private network in an authenticated
manner.
It's primary use right now is to allow the Encore platform a way to tunnel to your
[SQL database](https://encore.dev/docs/develop/databases) to perform the database migrations to your application and to
allow [access to the database from the Encore CLI](https://encore.dev/docs/develop/databases#connecting-to-databases)
## How it works
Emissary is split into two modules:
- [the `server` module](./server) which is the binary we deploy to your cloud.
- [the `library` module (this folder)](.) which serves as the client library and is used by our platform to establish connections.
The library provides a `emissary.Dialer` which provides a `Dial` and a `DialContext` method. These can be provided to most
Go networking enabled code as an underlying `Dial` function. When that other Go code tries to open a socket, it will use
the `emissary.Dialer` to establish the socket, which in-turn will be transparently routed through the Emissary server.
The Emissary server upon receiving the request, with authenticate the request using a shared secret key. Once
authenticated, the dialer can then request the server forwards the connection onto one of a predefined list of
allowed remote resources within the private network.
At the bottom most level, Emissary is simply a Socks 5 client/server however we wrap the socks 5 connection in a
transport layer, which allows us to run Emissary in various locations to adapt to requirements in the target cloud.
```
┌─────────────────────────────────────────────────────────────────────────┐
│Go `net.Conn` │
┌────────────────┐ │ ┌────────────────┐ ┌─────────────────────┐ ┌────────────────┐ │ ┌────────────────┐
│ │ │ │ │ │Transport Layer │ │ │ │ │ │
│ Go │ │ │ Emissary │ │ ┌─────────────────┐ │ │ Emissary │ │ │ Target │
│ ├───►│ │ ├────►│ │Socks 5 Protocol │ ├────►│ │ ├───►│ Remote │
│ Client │ │ │ Dialer │ │ └─────────────────┘ │ │ Server │ │ │ Resource │
│ │ │ │ │ │ │ │ │ │ │ │
└────────────────┘ │ └────────────────┘ └─────────────────────┘ └────────────────┘ │ └────────────────┘
│ │
└─────────────────────────────────────────────────────────────────────────┘
```
Currently, the only supported transport layer is a `websocket`; this transport layer allows Emissary to run behind HTTP
aware load balancers or in environments which only allow HTTP traffic in. In such environments we expect TLS termination
to have occurred at the edge before the code executes such as AWS Lambda functions.
To learn how to configure an Emissary server see [example.env](./server/example.env). The server will load the configuration
from either environmental variables or an `.env` file located within the working directory.
