@berish/stateful

Бинарный безопасный протокол организации транспорта для взаимодействия пиров с помощью отпечатков функций.

Является только уровнем организации транспорта (не является транспортом самостоятельно!).

Старая версия находится в npm как fartix-rfp

Installation

``
$ npm install @berish/rfp --save
`

or

`
$ yarn add @berish/rfp
`

Supports typescript

Инициализация

Нужно создать подключение с помощью socket.io (смотреть документацию к socketIO)

После настройки сокета мы можем инициализировать RfpPeer для дальнейшей работы

`typescript
const socketClientPeer = SocketIOClient.connect(socketServerAddress,{ transports: ['websocket'] });
const socketClientRfpPeer = new RfpPeer().setSocket(socketClientPeer));
socketClientPeer.on('connect', () => {
socketClientRfpPeer.open();
})
socketClientPeer.on('disconnect', () => {
socketClientRfpPeer.close();
})
`

Все! RfpPeer готов к работе. Пример выше показан для использования RfpPeer на стороне клиента, для сервера практически все аналогично

`typescript
const httpServer = http.createServer().listen();
const httpServerAddress = httpServer.address() as AddressInfo;
const socketServer = SocketIO(httpServer);

socketServer.on('connection', (socket) => {
const socketServerRfpPeer = new RfpPeer().setSocket(socket);
});
`

Настройка

$3

Можно удобно настраивать транспорт на лету.

`typescript
const peer = new RfpPeer();
peer.setSocket(socket: SocketIO.Client | SocketIO-Client.Socket);
`

$3

`typescript
peer.setSerberLevel(level: 'raw' | 'production')
`

Serber является реализацией библиотеки berish-serber. Служит для удобной сериализации и десериализации объектов. В случае установки значения в raw, RfpPeer будет общаться в сырых данных, которые получаются при обычной сериализации. Если стоит значение production, RfpPeer будет реализовывать умную поддержку функций и отпечатков функций.

По умолчанию стоит значение production.

$3

`typescript
peer.setStore(store: RfpStore)
`

Хранилище организовано с помощью реализации библиотеки berish-stober. Данная библиотека позволяет использовать любой адаптер хранилища, в том числе redux. Позволяет записывать данные в любой тип хранилища, например localStorage, после того, как будет описан адаптер типа хранилища storageAdapter (смотреть berish-stober).

`typescript
const store = new Stober.DynamicStore(redux.createStore, []);
const rfpStore = new RfpStore().setStoreAdapter(store);

const rfpPeer = new RfpPeer().setSocket(socket).setStore(rfpStore);
`

Взаимодействие

$3

Можно вручную открывать и закрывать контроль соединение (но не соединение транспорта)

`typescript
rfpPeer.open();
console.log(rfpPeer.isOpened);
rfpPeer.close();
`

По-умолчанию, при настройки транспорта автоматически открывается соединение прослушки транспорта для контроля RfpPeer.

$3

Клиент и сервер общаются посредством RfpChunk. Это является транспортной бизнес-сущностью, которая передает всю информацию между пирами.

`typescript
export type RfpResponseStatusType = 'resolve' | 'reject' | 'initial';

export interface IRfpChunkStore {
/* Ссылка на store внутри peer /
store?: RfpStore;
}

export interface IRfpChunkSend {
/* Показывает путь, на который направлен текущий chunk /
readonly path: string;
/* Основная информация, которую передает chunk /
readonly body?: Body;
}

export interface IRfpChunkId {
/* Показывает идентификатор текущего chunk /
chunkId?: string;
/* Показывает на какой chunk указывает текущий chunk /
replyId?: string;
/* Показывает запрос выполнен со статусом resolve или reject /
status?: RfpResponseStatusType;
}

export interface IRfpChunk
extends IRfpChunkSend,
IRfpChunkId,
IRfpChunkStore {
/* Дополнительная информация, которую можно получить из chunk /
aside?: { [key: string]: any };
}
`

$3

Чтобы отправить данные через rfp, необходимо вызвать метод send.

`typescript
const response = await socketClientRfpPeer.send({ body: 'hello world', path: 'hey' });
`

В данном случае клиент отправляет chunk по пути _‘hey’_ данные _‘hello world’_

Поле path является обязательным условием, но сами данные не являются обязательными, так как серверный peer имеет возможность не смотря на body отправить свой ответ.

Пример

`typescript
const lib = await socketClientRfpPeer.send({ path: ‘getLib’ });

// lib теперь имеет отпечатки функций сервера, где может вызывать функции библиотеки, которую ранее он получил
`

Формат отправки chunk

`typescript
export interface IRfpChunkSend {
body: any // любые данные
path: string // адрес, на который отправляется chunk,
chunkId: string // идентификатор текущего chunk, если не указывать, значение является уникальным
replyId: string // идентификатор chunk, на который направлен текущий chunk. В случае нахождение chunkId в базе прослушки, отвечает на chunk для которого он показывает
aside: {[key: string]: any} // дополнительная информация, которую можно отправить вместе с основной информацией (например, userToken)
status: ‘resolve’ | ‘reject’ | ‘initial’ // показывает, является ли это самостоятельным chunk (initial), либо отвечает на другой chunk в сети (resolve - успешно, reject - ошибка)
}
`

$3

Мы можем слушать любой chunk по пути path, после чего сработает callback, в который передаются 2 аргумента: request, next.

`typescript
interface IRfpRequest {
chunk: IRfpChunk;
peer: RfpPeer;
}

export type IRfpNextResponse = () => void;
`

Пример

`typescript
socketServerRfpPeer.receive(‘auth’, (request, next) => {
if(request.chunk.body.login !== ‘admin’ && request.chunk.body.pass !== ‘123456’ )
throw new Error(‘permission denied’);
return ‘access’;
});
`

Клиент в свою очередь получит ответ

`typescript
const response: IRfpChunk & IRfpReplyChunk = await socketClientRfpPeer.send({ body: { login: ‘admin’, pass: ‘123456’ }, path: ‘auth’ });

console.log(response.body) // access;
console.log(response.replyChunk.body) // { body: { login: ‘admin’, pass: ‘123456’ };
`

Отпечатки функций

Библиотека умеет эмулировать функции, которые вы можете передать с сервера на клиент и обратно. То есть теперь Вы можете отправлять не обычные текстовые данные (json), а полноценные переменные, объекты и функции.

Когда один пир отправляет другому пиру функцию или объект, в котором есть функция, эти функции преобразовываются в отпечатки функций. То есть это есть реальные функции, которые Вы в будущем сможете вызвать на клиенте. В этот момент произойдет запрос на сервер и вызовется настоящая функция, на которую и смотрит вызванный отпечаток этой функции. Вам не надо заботится о взаимодействии, библиотека это сделает за вас. Так ваши функции могут отправлять сами функции и объекты с функциями, они также будут автоматически преобразовываться в отпечатки функций. Стоит учитывать, если у вас на сервере функции являются синхронными, они преобразовываются в асинхронные (для клиента), для лучшей производительности JS движка. Вы можете отправлять функции с любого пира, все превращение сделает библиотека.

Пример

`typescript
const socketServerRfpPeer = new RfpPeer()
.setSocket(socketServerPeer);
const socketClientRfpPeer = new RfpPeer()
.setSocket(socketClientPeer);

const sumFunc = (a: number, b: number) => a + b;

socketServerRfpPeer.receive(‘getSum’, (req, next) => {
return sumFunc;
});

const lib = await socketClientRfpPeer.send({ path: ‘getSum’ });

const a = 13;
const b = 17;
const sum = await lib.body(a, b); // body - в данном случае будет отпечатком функции sumFunc
console.log(sum === sumFunc(a, b)) // 30 === 30
`

Поддерживается многоуровневая передача функций. Например, вложенность второго уровня

`typescript
const socketServerRfpPeer = new RfpPeer().setSocket(socketServerPeer);
const socketClientRfpPeer = new RfpPeer().setSocket(socketClientPeer);

const libServer = {
minus: (a, b) => a - b,
sum: (a, b) => a + b,
};
socketServerRfpPeer.receive('hey', (req, next) => {
return libServer;
});

const response = await socketClientRfpPeer.send({ path: 'hey' });
const libClient = response.body;

const a = 54;
const b = 32;
const sum = await libClient.sum(a, b);
const minus = await libClient.minus(a, b);
console.log(sum === libServer.sum(a, b)); // 86 === 86
console.log(minus === libServer.minus(a, b)); // 22 === 22
`

$3

Теперь Вы можете описывать свой бэкенд как библиотеку, не задумываясь о путях, и настройки роутингов для старого REST и о прочих трудностях. Вам только необходимо будет написать красивый бэкенд, не заботясь обо всех побочных задачах, которая вызывала ранее разработка бэкенда

`typescript
const socketServerRfpPeer = new RfpPeer().setSocket(socketServerPeer);
const socketClientRfpPeer = new RfpPeer().setSocket(socketClientPeer);

const books: { [id: string]: string } = {};

const libServer = {
book: {
create: (name: string) => {
const id = faker.random.uuid();
books[id] = name;
return id;
},
delete: (id: string) => {
delete books[id];
},
read: (id: string) => books[id],
update: (id: string, name: string) => {
books[id] = name;
return id;
},
},
};
socketServerRfpPeer.receive('hey', (req, next) => {
return libServer;
});

const libClient = await socketClientRfpPeer.send({ path: 'hey' });

const firstName = faker.name.title();
const idBook1 = await libClient.body.book.create(firstName);
let bookName = await libClient.body.book.read(idBook1);
console.log(bookName === firstName); // true

const secondName = faker.name.title();
await libClient.body.book.update(idBook1, secondName);
bookName = await libClient.body.book.read(idBook1);
console.log(bookName !== firstName); // true
console.log(bookName === secondName); // true

await libClient.body.book.delete(idBook1);
const bookName2 = await libClient.body.book.read(idBook1);
console.log(!!bookName2); // true
`

$3

Вы можете отправлять переменные, объекты, функции и всю прочую информацию между клиентами, не заботясь о настройках транспорта.

То есть, есть 2 клиента и 1 сервер. Вы можете перенаправлять информацию между клиентами через сервер, и все будет прекрасно работать. Если Вы хотите, чтобы общение происходило только через клиентов, без взаимодействия с сервером, вам необходимо настроить транспорт для P2P соединений, например, socket.io P2P или TCP (UDP) соединение (напомним, для socket.io P2P адаптер у нас уже готов, Вам необходимо только внести правки в режим транспорта socket.io, смотрите соответствующую документацию у них на сайте).

`typescript
const socketServerRfpPeer1 = new RfpPeer().setSocket(socketServerPeer1); // в данном случае это сокет, направленный на первого пира
const socketServerRfpPeer2 = new RfpPeer().setSocket(socketServerPeer2);// в данном случае это сокет, направленный на второго пира
const socketClientRfpPeer1 = new RfpPeer().setSocket(socketClientPeer1);
const socketClientRfpPeer2 = new RfpPeer().setSocket(socketClientPeer2);

socketServerRfpPeer1.receive('hey', async ({ chunk }, next) => {
const response = await socketServerRfpPeer2.send({ path: ‘hey’, body: chunk.body })
return response;
});
const lib = await socketClientRfpPeer1.send({
body: (data: string) => data && data.toLocaleUpperCase(),
path: 'hey',
});
const responseFromClientPeer2 = await lib.body('hello');
`

$3

Можно отправлять функции, которые находятся внутри какого-либо класса. Контекст слова this сохранится. Следует учитывать, что сам класс как класс передать не получится, отправится лишь объект представляющий данный класс, и ключевое слово this потеряет свой смысл если Вы завязаны на прототипе. Но если Вы хотите просто передать класс, не для работы с ним напрямую, а для вызова функций внутри этого класса, тогда все будет работать как надо.

Мы работает над тем, чтобы была какая-либо возможность передавать классы с прототипом в будущем напрямую.

Хранилище

Можно удобно хранить и использовать данные в общем хранилище. Так, Вы можете хранить _user token_ пользователя и в любой момент забирать его на сервере для своих проверок.

Хранилище использует реализацию библиотеки berish-stober (npm).

`typescript
const storeClient = new stober.DynamicStore(createStore, []);
const socketClientRfpStore = new RfpStore().setStoreAdapter(storeClient);

const socketClientRfpPeer = new RfpPeer().setSocket(socketClientPeer).setStore(socketClientRfpStore);
`

Вы можете использовать методы RfpStore для своих нужд.

`typescript
rfpStore.open(); // принудительное включение прослушки store
rfpStore.close(); // принудительная остановка прослушки store
rfpStore.isOpened; // прослушивается ли текущий store

rfpStore.state; // текущее состояние хранилище
rfpStore.setState(state); // задать текущий rfp.state по ключам из входящего state (как в react) и обновление на обеих сторонах
rfpStore.forceUpdate(); // принудительное обновление хранилище на обеих сторонах
rfpStore.setStateLocal(state); // похоже на setState, но не отправляет state на другой пир

rfpStore.get(key); // работа с полями через getter
rfpStore.set(key, value); // работа с полями через setter
`

Пример

`typescript
interface IState {
login: string;
}

const storeServer = new DynamicStore(createStore, []);
const storeClient = new DynamicStore(createStore, []);

const socketServerRfpStore = new RfpStore()
.setStoreAdapter(storeServer);
const socketClientRfpStore = new RfpStore()
.setStoreAdapter(storeClient);

const socketServerRfpPeer = new RfpPeer()
.setSocket(socketServerPeer)
.setStore(socketServerRfpStore);

const socketClientRfpPeer = new RfpPeer()
.setSocket(socketClientPeer)
.setStore(socketClientRfpStore);

socketClientRfpPeer.receive('hey', async ({ chunk }, next) => {
const state = chunk.store.state;
console.log(state) // {}
console.log(chunk.body) // {login: ‘admin’}
await chunk.store.setState(chunk.body);
return 'ok';
});

const status = await socketServerRfpPeer.send({ path: 'hey', body: { login: ‘admin’ } });

console.log(status.body) // ok
console.log(socketServerRfpPeer.store.state) // { login: ‘admin’ }
`

Middleware и Receivers. Цепочка выполнения запроса

Вы можете писать свои middleware или подключать сторонние. В них Вы можете описывать действия, которые необходимо совершить перед каждый получением данных на стороне одного из пира. Middleware получает на вход такой же request и next как и обычный receiver. Чтобы ответить на middleware необходимо вызвать метод next.

Если Вы ответите throw err или return data, Вы завершите цикл запроса и далее запрос не пойдет по цепочке, вместо этого пойдет ответный запрос на пир, который ожидает ответ. Если вы ответите next(), цепочка продолжится и будет вызываться другой middleware, если такой есть.

Если таковой отсутствует, запрос начнется по цепочке receivers на пути, которые были указаны в оригинальном chunk. Там также доступны 3 варианта ответа, которые работают аналогично, кроме next(). Метод next будет далее срабатывать по цепочке receivers с нужным path пока не будет получен ответ.

Если ответ никто так и не сформировал (отсутствуют middleware или все дали ответ next(), и отсутствуют receivers по нужному пути или все дали ответ next()) будет автоматически дан ответ reject с сообщением '_path is not found_'.

Пример

`typescript
const socketServerRfpPeer = new RfpPeer().setSocket(socketServerPeer);
const socketClientRfpPeer = new RfpPeer().setSocket(socketClientPeer);

const authMiddle: RfpMiddlewareReceive = ({ chunk, peer }, { reject, next }) => {
if (chunk.body.login === 'admin') return next();
throw new Error('its not admin');
};
socketServerRfpPeer.middleware(authMiddle);

socketServerRfpPeer.receive('hey', ({ chunk }, next) => {
if (chunk.body.password === '123456') return 'resolve by 1';
if (chunk.body.password === '1234567') return throw new Error('reject by 1');
return next();
});

socketServerRfpPeer.receive('hey', ({ chunk }, next) => {
if (chunk.body.password === '123123') return 'resolve by 2';
throw new Error('reject by 2');
});

// Примеры цепочки запросов

// Срабатывание middleware c ответом resolve
try {
const test = await socketClientRfpPeer.send({ path: 'hey', body: { login: 'admin2' } });
} catch (err) {
console.log(err); // its not admin
}

// Срабатывание второго receiver с ответом reject
try {
const test = await socketClientRfpPeer.send({ path: 'hey', body: { login: 'admin' } });
} catch (err) {
console.log(err); //reject by 2
}

// Срабатывание первого receiver с ответом reject
try {
const test = await socketClientRfpPeer.send({ body: { login: 'admin', password: '1234567' }, path: 'hey' });
} catch (err) {
console.log(err); //reject by 1
}

// Срабатывание первого receiver с ответом resolve
const test = await socketClientRfpPeer.send({ body: { login: 'admin', password: '123456' }, path: 'hey' });
console.log(test.body); //resolve by 1

// Срабатывание второго receiver с ответом resolve
const test = await socketClientRfpPeer.send({ body: { login: 'admin', password: '123123' }, path: 'hey' });
console.log(test.body); //resolve by 2
`

Контекст выполнения

Все хорошо, когда Вы напрямую ожидаете вызова через receivers, там Вы можете получить request напрямую, откуда можете считать любую информацию, например body или aside. Но что делать, когда Вы передали отпечаток функции и ожидаете вызова напрямую в функции? Изначально, в отпечаток функции не приходит request, потому что передача невозможно (ведь аргументы заняты Вами). В таком случае на помощь приходит небольшая магия.

$3

Например, Вы получили функции sum от сервера, которая просто суммирует 2 числа

`typescript
sum(a: number, b: number) {
return a + b;
}
`

Но что, если Вам надо проверить какое либо условие, например, может ли текущий пользователь суммировать числа, или выдать ему ошибка, что у Вас недостаточно прав.

`typescript
sum(a: number, b: number) {
if(chunk.store.state.userToken === undefined) throw new Error(‘permission denied’)
return a + b;
}
`

Но где же нам взять входящий chunk внутри функции? Для этого нужно прописать еще один аргумент, в который и будет передавать текущий request.

_ОБЯЗАТЕЛЬНО_: аргумент должен называться rfp и должен располагаться в конце всех аргументов; если аргумент будет назван по-другому, будет находиться не последним, либо не объявлен вообще, request передан не будет!

`typescript
sum(a: number, b: number, rfp?: IRfpChunk) {
const {chunk, peer} = rfp;
if(chunk.store.state.userToken === undefined) throw new Error(‘permission denied’)
return a + b;
}
`

Теперь магическим способом, мы получим request через аргумент rfp. Даже если Вы ожидаете любое количество аргументов, мы, если встретим среди них rfp, передадим Вам request.

Но что делать, если Вы ожидаете 2 аргумента, и второй из них может быть Вами не передан самостоятельно, например sum(3), когда sum(a: number, b?: number, rfp?: IRfpChunk). Тогда мы просто не передадим Вам этот второй аргумент, но rfp Вы получите в любом случае.

Если Вы хотите передать контекст временно (через aside), вы также его сможете легко получить (о том, как передавать контекст, читайте далее).

`typescript
sum(a: number, b: number, rfp?: IRfpChunk) {
const contextData = context.getContextAside(rfp);
if(contextData === undefined) throw new Error(‘permission denied’)
return a + b;
}
`

$3

Если Вы хотите при вызове функции через ее отпечаток передать дополнительный контекст, Вы можете воспользоваться функцией высшего порядка

`typescript
context.setContextAside(func, contextData);
`

Пример по отпечатку функции sum из прошлого примера

`typescript
const contextData = ‘123123’;
const sumWithContext = context.setContextAside(libClient.body.sum, contextData);

const sum = await sumWithContext(3, 4);
console.log(sum) // 7

const sumThrown = libClient.body.sum(3, 4) // thrown ‘permission denied’ (если вызывать без контекста функцию из прошлого примера)
``