# io.Gateway

[![npm version](https://img.shields.io/npm/v/@interopio/gateway.svg)](https://www.npmjs.com/package/@interopio/gateway)

## Overview

The `@interopio/gateway` package is the gateway for io.Connect Desktop/Browser.

## Table of Contents

- [Installation](#installation)
- [Requirements](#requirements)
- [Usage Examples](#usage-examples)
    - [Change Token TTL](#change-token-ttl)
    - [OAuth 2.0 Authenticator](#oauth-20-authenticator)
    - [Visibility](#visibility)
- [Changelog](#changelog)
- [License](#license)

## Installation

```shell
npm install @interopio/gateway@beta
```

## Requirements

- WebCrypto - [WebCrypto](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) is a standard API for
  performing cryptographic operations in web applications. It is supported in most modern browsers and Node.js
  environments. If running Node.js 18, you need to enable the `--experimental-global-webcrypto` flag, or set
  `globalThis.crypto` your self. For example `const { webcrypto } = require('crypto'); globalThis.crypto = webcrypto;`

- WebSocket - [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) is a protocol for full-duplex
  communication channels over a single TCP connection. It is supported in most modern browsers and Node.js environments.
  If running Node.js 18, you need to install the `ws` package. For example `npm install ws`.

## API docs

See [`gateway.md`](./gateway.md)

## Usage Examples

### Change Token TTL

```typescript
import Gateway from '@interopio/gateway'

const gateway = Gateway({
    token: {
        ttl: 1 * 24 * 60 * 60 // expiry of access tokens in seconds. 86400 is 1 day.
    }
});

await gateway.start();
```

### OAuth 2.0 Authenticator

To secure io.Gateway with OAuth 2.0 authentication services like auth0 or okta you need to configure

```typescript
import Gateway from '@interopio/gateway'

const gateway = Gateway({
    authentication: {
        default: 'oauth2',
        available: ['basic', 'oauth2'], // remove basic if want oauth2 only
        oauth2: {issuerBaseURL: 'https://<your-issuer-domain>', audience: 'https://<myapi>'}
    }
});

const client = gateway.client((msg) => console.log(msg));
const token = '<authorizationToken>';
client.send({type: 'hello', identity: {applicatoin: 'test'}, authentication: {method: 'access-token', token}});
```

### Metrics Publisher

```typescript
import Gateway from '@interopio/gateway'

const gateway = Gateway({
    metrics: {
        publishers: ['rest'],
        rest: {
            endpoint: 'http://localhost:8084/api/metrics',
            authentication: false
        }
    }
});
```

### Visibility

```typescript
import Gateway from '@interopio/gateway'

const gateway = Gateway({
    contexts: {
        visibility: [
            {context: /'___channel___.+'/, restrictions: 'cluster'},
            {context: /T42\..+/, restrictions: 'local'}
        ]
    },
    methods: {
        visibility: [
            {method: /T42\..+/, restrictions: 'local'}
        ]
    },
    peers: {
        visibility: [
            {domain: 'context', restrictions: 'cluster'},
            {domain: 'interop', restrictions: 'local'},
            {domain: 'bus', restrictions: 'local'}
        ]
    }
});
```

### Context Lifetime

```typescript
import Gateway from '@interopio/gateway'

const gateway = Gateway({contexts: {lifetime: 'retained'}});
```

### Cluster

You can use the `cluster` option to configure the cluster settings.

For example, to configure the cluster to use an io.Bridge instance running on `localhost:8084`, you can do the following:

```typescript
import Gateway from '@interopio/gateway';

const gateway = await IOGateway.Gateway({
    cluster: {
        // io.Bridge url
       endpoint: 'http://localhost:8084',
    }
});
```
## Changelog

See [changelog](./changelog.md)

## License

[MIT](license.md)