# Connect

`POST /nokku.v1.DaemonControlService/Connect`

Connect

Base URL: https://app.nokku.sh

## Authorization

- BearerAuth: HTTP bearer
- CookieAuth: API key in cookie `__Host-nokku_session`

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Connect-Protocol-Version` | header | number | no | Define the version of the Connect protocol |
| `Connect-Timeout-Ms` | header | number | no | Define the timeout, in ms |

## Request body (application/connect+json, required)

Also accepts: application/connect+proto, application/grpc, application/grpc+proto, application/grpc+json, application/grpc-web, application/grpc-web+proto, application/grpc-web+json.

- `heartbeat` (object)
  - `stateHash` (string): The state_hash of the last sync the daemon saved, empty before the first. bytes.max_len = 64
- `connectionReport` (object): ConnectionReport tells the core who logged in on the daemon's server and when they left. The daemon sends one report at a time and keeps its events until the ack. A report may so come twice, the core stores each event once.
  - `events` (array<nokku.v1.ConnectionEvent>)
  - `dropped` (integer): Events the daemon threw away since its last report, because it could keep no more.

Example:

```json
{
  "heartbeat": {
    "stateHash": "string"
  },
  "connectionReport": {
    "events": [
      {
        "connectionId": "84b500d7-71c8-4b1f-adf4-f1eb0000973d",
        "closed": true,
        "time": "2023-01-15T01:30:15.01Z",
        "principal": "string",
        "keyId": "string",
        "remoteAddr": "string",
        "clientVersion": "string",
        "relayed": true
      }
    ],
    "dropped": 0
  }
}
```

## Responses

### 200: Success

Returns `nokku.v1.ConnectResponse`.

- `stateUpdate` (object): StateUpdate tells a daemon what it should hold. It syncs when its own hash differs, or when this one is empty.
  - `stateHash` (string)
- `relayOpen` (object)
  - `relayId` (string)
  - `clientAddr` (string): The user's address as the core saw it. The daemon's sshd reports it as the remote address of the relayed connection.
- `connectionReportAck` (object): The core stored the report it got last.

```json
{
  "stateUpdate": {
    "stateHash": "string"
  },
  "relayOpen": {
    "relayId": "string",
    "clientAddr": "string"
  },
  "connectionReportAck": {}
}
```

### default: Error

Returns `connect.error`.

- `code` (string): The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. One of: `canceled`, `unknown`, `invalid_argument`, `deadline_exceeded`, `not_found`, `already_exists`, `permission_denied`, `resource_exhausted`, `failed_precondition`, `aborted`, `out_of_range`, `unimplemented`, `internal`, `unavailable`, `data_loss`, `unauthenticated`.
- `message` (string): A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
- `details` (array<connect.error_details.Any>): A list of messages that carry the error details. There is no limit on the number of messages.

```json
{
  "code": "not_found",
  "message": "string",
  "details": [
    {
      "type": "string",
      "value": "string",
      "debug": {}
    }
  ]
}
```

## Example request

```bash
curl -X POST 'https://app.nokku.sh/nokku.v1.DaemonControlService/Connect' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/connect+json' \
  -d '{
  "heartbeat": {
    "stateHash": "string"
  },
  "connectionReport": {
    "events": [
      {
        "connectionId": "84b500d7-71c8-4b1f-adf4-f1eb0000973d",
        "closed": true,
        "time": "2023-01-15T01:30:15.01Z",
        "principal": "string",
        "keyId": "string",
        "remoteAddr": "string",
        "clientVersion": "string",
        "relayed": true
      }
    ],
    "dropped": 0
  }
}'
```
