Make socket protocol/API public

[nikitabobko]

The way AeroSpace CLI communicates with the server is an implementation detail right now (unix socket + jsons). Nevertheless, some third-party applications already rely on it. Hopefully, the apps understand that the protocol is subject to breaking changes.

This issue is about making the protocol public and documented. For inspiration: https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#contentPart

TODO

• Migrate off the BlueSocket library dependency. I've used BlueSocket dependency in the early days of the project to speed up the development. There should be nothing hard about implementing unix socket communication by hand
• Prepend the message with how many bytes the message is going to be (Content-Length header). Right now, we just write json + EOF.
• Write an official Swift and Kotlin (languages I'm fluent in) libraries to communicate with AeroSpace socket. AeroSpace CLI itself could be migrated to the Swift library for uniformity
• Document the protocol

Known third-party apps that communicate with aerospace socket directly

• https://github.com/cristianoliveira/aerospace-ipc
• https://github.com/acsandmann/AeroSpaceLua
• https://github.com/search?q=%2Fbobko.aerospace.*%5C.sock%2F+-is%3Afork&type=code

Future directions

• Expose AeroSpace callbacks via socket protocol #1514

[acsandmann]

I would like to also suggest moving to native Mach Ports for performance reason as if we eventually have "dynamic" callbacks getting the message to the receiver quickly is very important. Plus, implementing a mach port server within aerospace would be relatively trivial. The only cost is breaking the now, somewhat significant amount of programs using the socket currently provided.

https://developer.apple.com/documentation/corefoundation/cfmachport?language=objc

very rudimentary server + client in swift

server

import Foundation
import Darwin.Mach

let service = "com.example.aerospace"

var recvPort: mach_port_t = 0
precondition(mach_port_allocate(mach_task_self_, MACH_PORT_RIGHT_RECEIVE, &recvPort) == KERN_SUCCESS)
precondition(mach_port_insert_right(mach_task_self_, recvPort,
                                  recvPort, mach_msg_type_name_t(MACH_MSG_TYPE_MAKE_SEND)) == KERN_SUCCESS)

service.withCString { cstr in
  let kr = bootstrap_register(bootstrap_port, cstr, recvPort)
  guard kr == KERN_SUCCESS else { fatalError("bootstrap_register failed \(kr)") }
}

print("Mach server running on \(service)")

let kBuf = 4096
let buf  = UnsafeMutableRawPointer.allocate(byteCount: kBuf, alignment: MemoryLayout<UInt32>.alignment)

while true {
 mach_msg(buf.assumingMemoryBound(to: mach_msg_header_t.self),
           MACH_RCV_MSG,
           0,
           mach_msg_size_t(kBuf),
           recvPort,
           0,
           MACH_PORT_NULL)

  let hdr = buf.assumingMemoryBound(to: mach_msg_header_t.self).pointee
  let msgBytes = Int(hdr.msgh_size) - MemoryLayout<mach_msg_header_t>.size
  let payload = Data(bytes: buf.advanced(by: MemoryLayout<mach_msg_header_t>.size), count: msgBytes)
  if let str = String(data: payload, encoding: .utf8) {
      print("received: '\(str)'")
  }

  guard hdr.msgh_remote_port != MACH_PORT_NULL else { continue }

  var replyHdr  = mach_msg_header_t()
  replyHdr.msgh_bits = MACH_MSGH_BITS_SET(MACH_MSG_TYPE_COPY_SEND, 0, 0, 0)
  replyHdr.msgh_size = hdr.msgh_size
  replyHdr.msgh_remote_port = hdr.msgh_remote_port
  replyHdr.msgh_local_port = MACH_PORT_NULL
  replyHdr.msgh_id = hdr.msgh_id

  memcpy(buf, &replyHdr, MemoryLayout<mach_msg_header_t>.size)
  memcpy(buf.advanced(by: MemoryLayout<mach_msg_header_t>.size),
         payload.withUnsafeBytes { $0.baseAddress }, msgBytes)

  mach_msg(buf.assumingMemoryBound(to: mach_msg_header_t.self),
           MACH_SEND_MSG,
           replyHdr.msgh_size,
           0,
           MACH_PORT_NULL,
           0,
           MACH_PORT_NULL)
}

client

import Foundation
import Darwin.Mach

let service = "com.example.aerospace"

var serverPort: mach_port_t = 0
service.withCString { cstr in
    let kr = bootstrap_look_up(bootstrap_port, cstr, &serverPort)
    guard kr == KERN_SUCCESS else { fatalError("bootstrap_look_up failed \(kr)") }
}

var replyPort: mach_port_t = 0
mach_port_allocate(mach_task_self_, MACH_PORT_RIGHT_RECEIVE, &replyPort)
mach_port_insert_right(mach_task_self_, replyPort,
                       replyPort, mach_msg_type_name_t(MACH_MSG_TYPE_MAKE_SEND))

let text = "hi"
let bytes = text.data(using: .utf8)!
let sendSize = MemoryLayout<mach_msg_header_t>.size + bytes.count
let buf = UnsafeMutableRawPointer.allocate(byteCount: sendSize, alignment: MemoryLayout<UInt32>.alignment)

var hdr = mach_msg_header_t()
hdr.msgh_bits = MACH_MSGH_BITS_SET(MACH_MSG_TYPE_COPY_SEND,
                                          MACH_MSG_TYPE_MAKE_SEND, 0, 0)
hdr.msgh_size = UInt32(sendSize)
hdr.msgh_remote_port = serverPort
hdr.msgh_local_port = replyPort
hdr.msgh_id = 0xCAFE

memcpy(buf, &hdr, MemoryLayout<mach_msg_header_t>.size)
bytes.withUnsafeBytes {
    memcpy(buf.advanced(by: MemoryLayout<mach_msg_header_t>.size), $0.baseAddress, bytes.count)
}

mach_msg(buf.assumingMemoryBound(to: mach_msg_header_t.self),
         MACH_SEND_MSG,
         hdr.msgh_size,
         0,
         MACH_PORT_NULL,
         0,
         MACH_PORT_NULL)

let kBuf = 4096
let rbuf = UnsafeMutableRawPointer.allocate(byteCount: kBuf, alignment: MemoryLayout<UInt32>.alignment)

mach_msg(rbuf.assumingMemoryBound(to: mach_msg_header_t.self),
         MACH_RCV_MSG,
         0,
         mach_msg_size_t(kBuf),
         replyPort,
         1000, 
         MACH_PORT_NULL)

let rhdr = rbuf.assumingMemoryBound(to: mach_msg_header_t.self).pointee
let rbytes = Int(rhdr.msgh_size) - MemoryLayout<mach_msg_header_t>.size
let rdata = Data(bytes: rbuf.advanced(by: MemoryLayout<mach_msg_header_t>.size), count: rbytes)

print("reply: '\(String(data: rdata, encoding: .utf8)!)'")

also, credit to sketchybar since i would not have known this is possible without.

[cristianoliveira]

Nice to see this happening!

I kinda jumped the gun, but when I started to work on the go library, I wanted to propose a way to reliable get the location of the socket file. I even prepared the lib to receive a Env AEROSPACESOCK variable so, in case it changes, I can configure it without having to recompile. I ended up implementing 2 extensions before that, but I'm fully aware that, as of now, it isn't a public API, but rather a "hack" 🙈

It would be nice to see something akin of sway's sway --get-socket or even to set it with a env variable like the SWAYSOCK or I3SOCK. For ref: https://man.archlinux.org/man/sway.1.en

[nikitabobko]

I would like to also suggest moving to native Mach Ports for performance reason

@acsandmann I am open to such suggestions, but I hesitate. I'm not familiar with mach ports, and apparently it's some Apple-specific API which means that not all languages will support it out of the box, compared to Unix sockets (Take Java for example which even refused to support unix sockets and only added them quite recently - https://openjdk.org/jeps/380).

It also looks like Apple themselves advice against using Mach ports:

Apple does not support Mach functions for use by external developers and does not guarantee the binary compatibility from one operating system release to the next of code that calls Mach directly

The solution that's on my mind right now is that we can just support both - sockets and Mach ports (with big screaming warning sign in the docs, that Apple advises against using Mach ports and breaking changes are possible). I think I want to delegate Mach ports supports to the community. In addition, the performance boost must be measured in the contributed PR to justify supporting Mach ports

---

I kinda jumped the gun

@cristianoliveira it's ok, I'm happy for libraries to work with aerospace sockets to appear

I wanted to propose a way to reliable get the location of the socket file

It would be nice to see something akin of sway's sway --get-socket or even to set it with a env variable like the SWAYSOCK or I3SOCK

What is not reliable about the current way? I think that hardcoded and predefined path works perfectly fine. I actually think that making it configurable is worse because it creates room for disagreement between clients and the server.

[acsandmann]

i think "Apple does not support Mach functions for use by external developers and does not guarantee the binary compatibility from one operating system release to the next of code that calls Mach directly" makes it a quasi undocumented api so maybe we should not be using it in AeroSpace or atleast we should mark it behind a flag.

i agree that supporting both with a warning is probably the best idea but before any implementation is fleshed out we should or i or someone should measure the performance impact to see if it is even a good idea. also, client implementations would also likely have to be done as i dont think many people would want to or could easily implement a mach client.