# conduit

## Description

Opening a two-way WebSocket is a very common software pattern. The `conduit` operator makes it trivially easy to initiate this exchange with a Socket.io server. It pipes an Observable into a two-way websocket. Each item in the Observable will be published to the server. The output stream will be the messages sent from the server to the client.

Messages sent to the `conduit` operator can include any keys you want. But two keys (`topic` and `binary`) are reserved and `conduit` will handle them differently. (See below for more information.)

## Usage

**Basic Usage**: The most common use for WebSockets is to open a bi-directional data stream to publish messages to the server and receive messages back from it. The package provides a `conduit` operator for this purpose:

```javascript
import { from } from 'rxjs';
import { conduit } from '@bottlenose/rxsocketio';

const messagesToSend$ = from([
  {body: 'data'},
  {body: 'more data'},
]);

// send messages over the WebSocket and receive messages back from it...
const socketResponse$ = messageToSend$.pipe(
  conduit({url: 'http://mysite.com'})
);
socketResponse$.subscribe(
  console.log, // log all messages received from the server
  console.error,
  () => console.log('Socket Closed!') 
);
```

## Sending messages to a topic

Socket.io supports "topics" for messages. By default, objects piped into the `conduit` operator are sent to the `'message'` topic. You can simply add a topic key to the objects to send them to a particular topic:

```javascript
import { from } from 'rxjs';
import { conduit } from '@bottlenose/rxsocketio';

const messagesToSend$ = from([
  {body: 'Network TV is overrated', topic: 'television'},
  {body: 'The Beatles are really, really good.', topic: 'music'},
]);

// send messages over the WebSocket and receive messages back from it...
const socketResponse$ = messageToSend$.pipe(
  conduit({url: 'http://mysite.com', topics: ['television', 'music', 'message']})
);
socketResponse$.subscribe(
  console.log, // log all messages received from the server
  console.error,
  () => console.log('Socket Closed!')
);
```

## Sending messages with binary

Sometimes, it's useful to send binary data (like audio or video) using Socket.io. The `conduit` operator supports this:

```javascript
import {from} from 'rxjs';

// binary can be an ArrayBuffer, Uint8Array, Blob, File and Buffer
const messageToSend$ = from([
  {topic: 'audio-stream', binary: new Uint8Array(), part: 0},
  {topic: 'audio-stream', binary: new Uint8Array(), part: 1},
  {topic: 'audio-stream', binary: new Uint8Array(), part: 0},
]);

// the messages will be sent to Socket.io like this:
// socket.emit('audio-stream', jsonData, binary);
// and the server can parse the results like this:
// socket.on('audio-stream', jsonData, binary);
const socketResponse$ = messageToSend$.pipe(
  conduit({url, topics: ['audio-chunk-received']})
);
socketResponse$.subscribe(
  console.log, // log all messages received from the server
  console.error,
  () => console.log('Socket Closed!')
);
```

## Advanced options

You can also provide `socketOptions`, which will be passed into the [Socket.io Manager](https://socket.io/docs/client-api/):

```javascript
import { from } from 'rxjs';
import { conduit } from '@bottlenose/rxsocketio';

const messagesToSend$ = from([
  {body: 'Network TV is overrated', topic: 'television'},
  {body: 'The Beatles are really, really good.', topic: 'music'},
]);

// You can override defaults by passing any of the options that can normally
// be given to a socket.io Manager object:
const socketOptions = {
  query: {token: 'mysuperseeeecrettoken'},
  transports: ['websocket'],
  timeout: 5000,
};

// send messages over the WebSocket and receive messages back from it...
const socketResponse$ = messageToSend$.pipe(
  conduit({url: 'http://mysite.com', socketOptions})
);
socketResponse$.subscribe(
  console.log, // log all messages received from the server
  console.error,
  () => console.log('Socket Closed!')
);
```

## API

```
conduit({
  url<String>,
  [topics[String]],
  [socketOptions[Object]]
})
```

### Since

0.5

### Parameters

* `url<String>`: The URL of the backend server (like "<http://localhost:3000>").

### Options

* `topics[String]`: Topics to subscribe to when receiving messages from the server. Defaults to `['message']`.
* `socketOptions[Object]`: Options to pass into the [socket.io Manager](https://socket.io/docs/client-api/).
* `stop$[Observable]`: The conduit and its observable will terminate (and disconnect) if the stop$ observable emits any items.&#x20;

### Returns

&#x20;Returns the stream of messages from the server.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://brianbuccaneer.gitbook.io/bottlenose/dev-2/sources-and-sinks/rxsocketio/operators/conduit.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.