From Woozle Writes Code
Jump to navigation Jump to search


The key idea here is to make it easier for any language to make use of libraries written in any other language, and for compiled languages to make use of compiled libraries without having to recompile and link them[1]. It also is especially useful in integrated development environments with code-aware autocompletion (CAA) features, in that it provides the necessary information for CAA when using a library whose source-code is not included in the project.

The inspiration for FerretX is a Microsoft technology which I think was called "ActiveX DLLs", but the Wikipedia entry on ActiveX only mentions it in passing and certainly doesn't do credit to how useful it was in environments like Visual Basic 6 and Access 97. One important difference, though, is that while ActiveX DLLs could be served from a remote machine (via Network Neighborhood), they always executed locally (to the best of my knowledge); FerretX is intended to run on the file-host, either executed directly by an authorized ssh user or indirectly via an appropriately-configured httpd server. The latter option offers some possibilities for finally replacing the awkward HTML+JS paradigm for remote-running graphical applications.

The immediate needs for this:

  • I want to use certain libraries in PHP that are well-supported for other languages but either not available in PHP at all or else poorly supported.
  • I want to be able to talk via ssh to database engines that are closed to direct outside access.
    • A simple server-side FerretX app will expose an API for local database interaction.
      • Would this be a security-hole? Kind of not really; you still need ssh access and the right to run the program in question. ...and since it's only intended for administrative sorts of uses, it could be disabled most of the time, and all accesses could be logged and reported, if need be.


The idea is to use JSON[2] to communicate:

  • class/object interfaces
  • object data

We will need to start with:

  • a command to retrieve all interfaces
  • a command to retrieve the details of a particular interface
  • a standard structure for defining method APIs (static/dynamic, paramter/type list, return type)
  • a way to call any given method within an interface (directly for static methods, or with an object as an implicit argument for dynamic methods)


Sequence of Events

  • The client checks that the server is loaded. (The server can either be always-running or load-on-request, individual threads or common thread.) For the first implementation, the server will be a standalone process that the client loads when needed.
  • The client requests the server's status. If the server reports an error, or does not respond properly, then the client passes that information back to the user in some appropriate way.

Data Format

All communication takes place by passing structured keyed arrays back and forth. For the first implementation, I'll be using JSON as the encoding format, but any other serialization format (such as YAML or XML) should work, as long as both client and server can speak it.

What is particular to this usage is the content of the structure being conveyed.

The following is tentative and experimental.

Each communication between client and server is called a message. We'll call query/request messages "questions", and response/information/result messages "answers". When a question is answered more than once (to provide newer information), the answer is also an update.

Note that because we're treating all messages as representations of an array-structure, any item which has sub-items cannot also have a single scalar value; any data must be in one or more named sub-items.

The array-structure for each of these message-types:

Question Answer
  • {topic name}
    • argument_name = {argument value}
    • argument_name = {argument value}
    • ...
  • {topic name}
    • status
      • code = {status code}
      • text = {description of status}
    • data...

"Topic name" can be thought of as being like a command or function-name.

Most messages will be in an object-context; only the top-level API-query dialogue takes place without specifying an object.

API questions:

  • "identify": asks the server to confirm its identity and return version information (the server will also do this automatically when first started)
    • "name" = short name of program/library
    • "summary" = one-line description
    • "version" = version string
  • "classes": asks the server for a list of classes/interfaces
    • Each class may then be queried for details.
    • TODO: We might want to include some overall details about each class (attributes, inheritance?)



I need to understand Spritely Goblins and OCapN, which sound like one or the other of them might be basically the same idea. It certainly sounds like it ends up supporting similar capabilities.

Related, but not the same thing:

  • PHP Foreign Function Interface: allows calling compiled libraries (.so/.DLL) directly, but is a bit slow
  • SOAP: seems unnecessarily complicated, and may not serve the same goals


    1. In the case of interpreted languages, this often means recompiling the language interpreter itself, which can create a technical debt situation since the standard package updates can no longer be used
    2. or any other widely-supported open protocol that can encode arbitrary data-structures as text in a binary-safe way