Support Ukraine

While you're reading this text we're suffering from russia's bombs. Please help us to stand against russia's invasion and prevent World War III. It's pretty easy with UNITED24 fundraising platform. Thank you!

YueS (Yue library Server)

This project aims to provide the power of Yue for any language/framework without need in modification of runtime core sources.
Written in Lua 5.1 with LuaJIT as a runtime core.

External dependencies:

• Lua5.1 bindings for Yue library
• LuaFileSystem for Lua 5.1
• LuaSocket for Lua 5.1

Bundled dependencies:

• lua-uuid.lua
• JSON.lua

Usage

Server should be created as a subprocess of your app. On Unix-like systems there is need to create two named FIFOs and provide their paths to the server using CLI args:

$ yues /path/to/infifo /path/to/outfifo

Naming description: infifo is the FIFO your program writes to, outfifo is the FIFO your program reads from.

Main principles

The idea of such server is allowance of executing arbitrary code on server side and get the results on client side. Any definitions of components should be implemented on client side (example). That's why this server is compatible with any Yue library version. Needed library version also should be checked at the client side (example).

Messaging protocol

Each message is a JSON-encoded object with one required prop — type that is string and describes the type of the message. The rest props are defined according to the type of the message. Each message should have newline ending (U+000A)

Server-sent messages (outfifio)

• INIT

  Sent once after server is initialized. Has no more props

• POSTMESSAGE

  Sent right after global postMessage has been called. List of props:

  
  val — any, the value that is passed to postMessage call. Can be of any serializable type

• CREATE_R

  The result of function creation

  
  id — string, the id passed to CREATE call
  res — optional, string, the id of created function
  err — optional, string, the error message if there is an error

• CALL_R

  The result of function call

  
  id — string, the id passed to CALL call
  res — optional, any, the result of function call. May be of any serializable type
  err — optional, string, the error message if there is an error

• REMOVE_R

  The result of function removal

  
  id — string, the id passed to REMOVE call

• IIFE_R

  The result of function creation and immidiate invocation

  
  id — string, the id passed to IIFE call
  res — optional, any, the result of function call. May be of any serializable type
  err — optional, string, the error message if there is an error

Client-sent messages (infifo)

• CREATE

  Creates the function and returns it's id. See Function scope section.

  
  id — string, the id of the call, pseudorandom string used to properly corellate and get back result of the invocation. It's recommended to use UUIDv4
  args — Array<string>, list of argument names to be passed to the function at its invocation
  body — string, the body of the function written in Lua 5.1

• CALL

  Calls already created function by it's id

  
  id — string, the id of the call, pseudorandom string used to properly corellate and get back result of the invocation. It's recommended to use UUIDv4
  ref — string, the id of the function to be invoked
  args — Array<any>, the arguments passed to function call

• REMOVE

  Removes already created function by it's id

  
  id — string, the id of the call, pseudorandom string used to properly corellate and get back result of the invocation. It's recommended to use UUIDv4
  ref — string, the id of the function to be removed

• IIFE

  Creates function, invokes it, returns the result and removes the function immidiately. See Function scope section.

  
  id — string, the id of the call, pseudorandom string used to properly corellate and get back result of the invocation. It's recommended to use UUIDv4
  argNames — Array<string>, list of argument names to be passed to the function at its invocation
  body — string, the body of the function written in Lua 5.1
  args — Array<any>, the arguments passed to function call

Function scope

There are some new globals available:

• gui — object that contains all the stuff from Yue lib. The same as require('yue.gui')

• JSON — JSON reader/encoder (see JSON.lua in Bundled dependencies section)

• postMessage — method that sends POSTMESSAGE with a value passed to the method. Usable for sending event messages.

  Signature: postMessage(value: any): void

• sleep — method that temporarily stops the invocation for specified period of time in seconds.

  Signature: sleep(seconds: number): void

• __readMessagesSync — method that synchronously reads new messages from infifo and invokes messaging.onmessage for each new message.

  Signature: __readMessagesSync(): void

• __getFunction — method that returns a function that was previously created with a CREATE call by specified id.

  Signature: __getFunction(ref: string): (...args: any[]) => any