Metacom Communication Protocol for Metarhia


Metacom protocol specification:
https://github.com/metarhia/Contracts/blob/master/doc/Metacom.md

``js
import { Metacom } from 'metacom';
// const { Metacom } = require('metacom'); // for backend

const metacom = Metacom.create('ws://domainname.com:8000');
const { api } = metacom;
try {
await metacom.load('auth'); // Load auth interface
await api.auth.status(); // Check session status
} catch (err) {
await api.auth.signIn({ login: 'marcus', password: 'marcus' });
}
await metacom.load('example'); // Load example interface
const result = api.example.methodName({ arg1, arg2 });
`

Streams over Websocket

$3

Create uploadFile function on the client:

`js
const metacom = Metacom.create('ws://example.com/api');

const uploadFile = async (file) => {
// createBlobUploader creates streamId and inits file reader for convenience
const uploader = metacom.createBlobUploader(file);
// Prepare backend file consumer
await metacom.api.files.upload({
streamId: uploader.streamId,
name: file.name,
});
// Start uploading stream and wait for its end
await uploader.upload();
return { uploadedFile: file };
};
`

Create API method to init file destination:

`js
// api/files/upload.js
async ({ streamId, name }) => {
const filePath = ./application/resources/${name};
// Get incoming stream by streamId sent from client
const readable = context.client.getStream(streamId);
// Create nodejs stream to write file on server
const writable = node.fs.createWriteStream(filePath);
// Pipe metacom readable to nodejs writable
readable.pipe(writable);
return { result: 'Stream initialized' };
};
`

$3

Create downloadFile function on the client:

`js
const metacom = Metacom.create('ws://example.com/api');

const downloadFile = async (name) => {
// Init backend file producer to get streamId
const { streamId } = await metacom.api.files.download({ name });
// Get metacom readable stream
const readable = await metacom.getStream(streamId);
// Convert stream to blob to make a file on the client
const blob = await readable.toBlob();
return new File([blob], name);
};
`

Create API method to init file source:

`js
// api/files/download.js
async ({ name }) => {
const filePath = ./application/resources/${name};
// Create nodejs readable stream to read a file
const readable = node.fs.createReadStream(filePath);
// Get file size
const { size } = await node.fsp.stat(filePath);
// Create metacom writable stream
const writable = context.client.createStream(name, size);
// Pipe nodejs readable to metacom writable
readable.pipe(writable);
return { streamId: writable.streamId };
};
``

License & Contributors

Copyright (c) 2018-2025 Metarhia contributors.
Metacom is MIT licensed.\
Metacom is a part of Metarhia technology stack.