You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@opendal.apache.org by ps...@apache.org on 2026/09/25 12:34:43 UTC
(opendal-yinyang) 04/06: feat: connect a native FSKit prototype to managed storage (#63)
This is an automated email from the ASF dual-hosted git repository.
PsiACE pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/opendal-yinyang.git
commit 63ad20f50604c19edae88c8becc3a563dce36a22
Author: Xuanwo <gi...@xuanwo.io>
AuthorDate: Fri Sep 25 20:34:27 2026 +0800
feat: connect a native FSKit prototype to managed storage (#63)
Co-authored-by: Chojan Shang <ps...@apache.org>
---
platforms/macos/FSKit/FSKit.entitlements | 8 +
platforms/macos/FSKit/FileSystem.swift | 356 ++++++++++++++++++++++++++++++
platforms/macos/FSKit/Info.plist | 40 ++++
platforms/macos/Host/App.swift | 36 +++
platforms/macos/Host/Host.entitlements | 6 +
platforms/macos/README.md | 60 +++++
platforms/macos/Shared/NativeBridge.swift | 109 +++++++++
platforms/macos/project.yml | 63 ++++++
specs/README.md | 1 +
specs/macos-frontends.md | 49 ++++
xtask/src/main.rs | 73 ++++++
11 files changed, 801 insertions(+)
diff --git a/platforms/macos/FSKit/FSKit.entitlements b/platforms/macos/FSKit/FSKit.entitlements
new file mode 100644
index 0000000..8f89b37
--- /dev/null
+++ b/platforms/macos/FSKit/FSKit.entitlements
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+<key>com.apple.security.app-sandbox</key><true/>
+<key>com.apple.security.network.client</key><true/>
+<key>com.apple.developer.fskit.fsmodule</key><true/>
+</dict></plist>
+
diff --git a/platforms/macos/FSKit/FileSystem.swift b/platforms/macos/FSKit/FileSystem.swift
new file mode 100644
index 0000000..56b7563
--- /dev/null
+++ b/platforms/macos/FSKit/FileSystem.swift
@@ -0,0 +1,356 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+
+import Foundation
+import FSKit
+import OSLog
+
+@main
+struct YinYangExtension: UnaryFileSystemExtension {
+ var fileSystem: FSUnaryFileSystem & FSUnaryFileSystemOperations { YinYangFileSystem() }
+}
+final class YinYangFileSystem: FSUnaryFileSystem, FSUnaryFileSystemOperations {
+ private var resource: FSPathURLResource?
+ private let queue = DispatchQueue(label: "org.apache.yinyang.fskit.lifecycle")
+ func probeResource(resource: FSResource, replyHandler: @escaping (FSProbeResult?, Error?) -> Void) {
+ guard resource is FSPathURLResource else { return replyHandler(nil, POSIXError(.ENODEV)) }
+ replyHandler(.usable(name: "YinYang", containerID: FSContainerIdentifier(uuid: UUID())), nil)
+ }
+ func loadResource(resource: FSResource, options: FSTaskOptions, replyHandler: @escaping (FSVolume?, Error?) -> Void) {
+ queue.async {
+ guard self.resource == nil, let resource = resource as? FSPathURLResource,
+ resource.url.startAccessingSecurityScopedResource() else {
+ return replyHandler(nil, POSIXError(.EACCES))
+ }
+ do {
+ let data = try Data(contentsOf: resource.url.appendingPathComponent("volume.json"))
+ guard var config = try JSONSerialization.jsonObject(with: data) as? [String: Any] else { throw POSIXError(.EINVAL) }
+ // Staging stays inside the explicitly selected isolated resource.
+ config["staging"] = resource.url.appendingPathComponent("mount-state").path
+ let bridge = try NativeBridge(config: config, mode: "mount")
+ let volume = try YinYangVolume(bridge: bridge)
+ self.resource = resource
+ self.containerStatus = .ready
+ replyHandler(volume, nil)
+ } catch {
+ resource.url.stopAccessingSecurityScopedResource()
+ replyHandler(nil, (error as? NativeFailure)?.posix ?? error)
+ }
+ }
+ }
+ func unloadResource(resource: FSResource, options: FSTaskOptions, replyHandler: @escaping (Error?) -> Void) {
+ queue.async {
+ self.resource?.url.stopAccessingSecurityScopedResource()
+ self.resource = nil
+ replyHandler(nil)
+ }
+ }
+}
+final class YinYangItem: FSItem {
+ let identity: String
+ let number: UInt64
+ var metadata: NativeItem
+ init(_ metadata: NativeItem, number: UInt64) {
+ identity = metadata.node
+ self.number = number
+ self.metadata = metadata
+ super.init()
+ }
+}
+final class YinYangVolume: FSVolume, FSVolume.Handler, FSVolume.ReadWriteHandler, FSVolume.DataCacheHandler {
+ let bridge: NativeBridge
+ let root: YinYangItem
+ private let queue = DispatchQueue(label: "org.apache.yinyang.fskit.requests")
+ private var items: [String: YinYangItem] = [:]
+ private var numbers: [String: UInt64] = [:]
+ private var nextID: UInt64 = 3
+ private var enumerations: [UInt64: (String, String)] = [:]
+ private var nextVerifier: UInt64 = 1
+ private var references: [String: Int] = [:]
+ private let logger = Logger(subsystem: "org.apache.yinyang.fskit", category: "io")
+ init(bridge: NativeBridge) throws {
+ self.bridge = bridge
+ let metadata = try bridge.item(["op": "root"])
+ root = YinYangItem(metadata, number: 2)
+ super.init(volumeID: FSVolume.Identifier(uuid: UUID(uuidString:
+ metadata.node.prefix(8) + "-" + metadata.node.dropFirst(8).prefix(4) + "-" +
+ metadata.node.dropFirst(12).prefix(4) + "-" + metadata.node.dropFirst(16).prefix(4) + "-" +
+ metadata.node.dropFirst(20)) ?? UUID()), volumeName: FSFileName(string: "YinYang"))
+ items[root.identity] = root
+ numbers[root.identity] = 2
+ }
+ private func item(_ raw: FSItem) throws -> YinYangItem {
+ guard let item = raw as? YinYangItem else { throw POSIXError(.EINVAL) }
+ return item
+ }
+ private func number(_ identity: String) -> UInt64 {
+ if let number = numbers[identity] { return number }
+ let number = nextID
+ nextID += 1
+ numbers[identity] = number
+ return number
+ }
+ private func remember(_ metadata: NativeItem) -> YinYangItem {
+ if let item = items[metadata.node] {
+ // A pinned directory enumeration may outlive a newer observation.
+ // Do not publish old attributes with a newer FSKit sequence number.
+ if metadata.generation >= item.metadata.generation { item.metadata = metadata }
+ return item
+ }
+ let item = YinYangItem(metadata, number: number(metadata.node))
+ items[metadata.node] = item
+ return item
+ }
+ private func attrs(_ item: YinYangItem) -> FSItem.Attributes {
+ let m = item.metadata
+ let result = FSItem.Attributes()
+ result.type = m.directory ? .directory : .file
+ result.fileID = FSItem.Identifier(rawValue: item.number)!
+ result.parentID = FSItem.Identifier(rawValue: number(m.parent ?? root.identity))!
+ result.size = m.size
+ result.allocSize = m.size
+ result.mode = m.directory || m.executable ? 0o755 : 0o644
+ result.uid = getuid()
+ result.gid = getgid()
+ result.linkCount = m.directory ? 2 : 1
+ result.flags = 0
+ result.modifyTime = timespec(tv_sec: Int(clamping: m.generation), tv_nsec: 0)
+ result.changeTime = result.modifyTime
+ result.accessTime = result.modifyTime
+ result.birthTime = timespec(tv_sec: 0, tv_nsec: 0)
+ return result
+ }
+ private func perform<T>(_ operation: @escaping () throws -> T, _ reply: @escaping (T?, Error?) -> Void) {
+ queue.async {
+ do { reply(try operation(), nil) }
+ catch {
+ self.logger.error("Operation failed: \(String(describing: error), privacy: .public)")
+ reply(nil, (error as? NativeFailure)?.posix ?? error)
+ }
+ }
+ }
+ private func checked<T>(_ result: T?) throws -> T {
+ guard let result else { throw POSIXError(.EIO) }
+ return result
+ }
+ var volumeStatistics: FSStatFSResult {
+ let result = FSStatFSResult(fileSystemTypeName: "yinyang")
+ result.blockSize = 4096
+ result.ioSize = 64 * 1024
+ return result
+ }
+ var supportedVolumeCapabilities: FSVolume.SupportedCapabilities {
+ let result = FSVolume.SupportedCapabilities()
+ result.caseFormat = .insensitiveCasePreserving
+ result.doesNotSupportVolumeSizes = true
+ result.doesNotSupportSettingFilePermissions = true
+ result.supportsSparseFiles = true
+ return result
+ }
+ var maximumLinkCount: Int { 1 }
+ var maximumNameLength: Int { 255 }
+ var restrictsOwnershipChanges: Bool { true }
+ var truncatesLongNames: Bool { false }
+ var maximumFileSizeInBits: Int { 63 }
+ var maximumXattrSizeInBits: Int { 0 }
+ func activateVolume(options: FSTaskOptions, replyHandler: @escaping (FSActivateResult?, Error?) -> Void) { replyHandler(FSActivateResult(rootItem: root), nil) }
+ func deactivateVolume(options: FSDeactivateOptions, replyHandler: @escaping (Error?) -> Void) { replyHandler(nil) }
+ func mount(options: FSTaskOptions, replyHandler: @escaping (Error?) -> Void) { replyHandler(nil) }
+ func unmount(replyHandler: @escaping () -> Void) { queue.async { replyHandler() } }
+ func synchronize(flags: FSSyncFlags, replyHandler: @escaping (Error?) -> Void) {
+ perform({ try self.bridge.call(["op": "fsync"]) }) { _, error in replyHandler(error) }
+ }
+ func getAttributes(_ desiredAttributes: FSItem.GetAttributesRequest, of raw: FSItem, context: FSContext, replyHandler: @escaping (FSGetAttributesResult?, Error?) -> Void) {
+ perform({
+ let item = try self.item(raw)
+ if !item.metadata.directory { try self.refresh(item) }
+ do { item.metadata = try self.bridge.item(["op": "node", "node": item.identity]) }
+ catch let error as NativeFailure where error.kind == "NotFound" { /* Retained open-unlink metadata. */ }
+ return try self.checked(FSGetAttributesResult(attributes: self.attrs(item)))
+ }, replyHandler)
+ }
+ func setAttributes(_ requested: FSItem.SetAttributesRequest, on raw: FSItem, context: FSContext, replyHandler: @escaping (FSSetAttributesResult?, Error?) -> Void) {
+ perform({
+ let item = try self.item(raw)
+ // Validate the complete request before making any content change.
+ if requested.isValid(.mode) && requested.mode & 0o7777 != self.attrs(item).mode { throw POSIXError(.ENOTSUP) }
+ if requested.isValid(.flags) && requested.flags != 0 { throw POSIXError(.ENOTSUP) }
+ if requested.isValid(.uid) && requested.uid != getuid() { throw POSIXError(.ENOTSUP) }
+ if requested.isValid(.gid) && requested.gid != getgid() { throw POSIXError(.ENOTSUP) }
+ for attribute: FSItem.Attribute in [.accessTime, .modifyTime, .changeTime, .birthTime, .backupTime, .addedTime, .allocSize] {
+ if requested.isValid(attribute) { throw POSIXError(.ENOTSUP) }
+ }
+ if requested.isValid(.size) {
+ try self.bridge.call(["op": "truncate", "node": item.identity, "length": requested.size])
+ requested.consumedAttributes.insert(.size)
+ }
+ for attribute: FSItem.Attribute in [.mode, .flags, .uid, .gid] {
+ if requested.isValid(attribute) { requested.consumedAttributes.insert(attribute) }
+ }
+ item.metadata = try self.bridge.item(["op": "node", "node": item.identity])
+ return try self.checked(FSSetAttributesResult(attributes: self.attrs(item), freeSpace: nil))
+ }, replyHandler)
+ }
+ func lookupItem(named name: FSFileName, in directory: FSItem, context: FSContext, replyHandler: @escaping (FSLookupItemResult?, Error?) -> Void) {
+ perform({
+ guard let name = name.string else { throw POSIXError(.EINVAL) }
+ let directory = try self.item(directory)
+ if name == "." { return directory }
+ if name == ".." {
+ guard let parent = directory.metadata.parent else { return self.root }
+ return self.remember(try self.bridge.item(["op": "node", "node": parent]))
+ }
+ return self.remember(try self.bridge.item(["op": "lookup", "parent": directory.identity, "name": name]))
+ }) { (item: YinYangItem?, error) in
+ replyHandler(item.flatMap { FSLookupItemResult(foundItem: $0, itemName: FSFileName(string: $0.metadata.name), itemAttributes: self.attrs($0)) }, error)
+ }
+ }
+ func reclaimItem(_ raw: FSItem, replyHandler: @escaping (Error?) -> Void) {
+ perform({
+ let item = try self.item(raw)
+ var failure: Error?
+ _ = item.tryReclaim {
+ do { try self.bridge.call(["op": "release", "node": item.identity]) }
+ catch { failure = error }
+ }
+ if let failure { throw failure }
+ // Keep the numeric identity stable for the lifetime of the volume.
+ return true
+ }) { _, error in replyHandler(error) }
+ }
+ func readSymbolicLink(_ item: FSItem, context: FSContext, replyHandler: @escaping (FSReadSymlinkResult?, Error?) -> Void) { replyHandler(nil, POSIXError(.ENOTSUP)) }
+ func createSymbolicLink(named name: FSFileName, in directory: FSItem, attributes: FSItem.SetAttributesRequest, linkContents: FSFileName, context: FSContext, replyHandler: @escaping (FSCreateSymlinkResult?, Error?) -> Void) { replyHandler(nil, POSIXError(.ENOTSUP)) }
+ func createLink(to item: FSItem, named name: FSFileName, in directory: FSItem, context: FSContext, replyHandler: @escaping (FSCreateLinkResult?, Error?) -> Void) { replyHandler(nil, POSIXError(.ENOTSUP)) }
+ func createItem(named name: FSFileName, type: FSItem.ItemType, in directory: FSItem, attributes: FSItem.SetAttributesRequest, context: FSContext, replyHandler: @escaping (FSCreateItemResult?, Error?) -> Void) {
+ perform({
+ guard type == .file || type == .directory, let name = name.string else { throw POSIXError(.ENOTSUP) }
+ if attributes.isValid(.mode) && type == .file && attributes.mode & 0o111 != 0 { throw POSIXError(.ENOTSUP) }
+ if attributes.isValid(.size) && attributes.size != 0 { throw POSIXError(.ENOTSUP) }
+ if attributes.isValid(.flags) && attributes.flags != 0 { throw POSIXError(.ENOTSUP) }
+ let parent = try self.item(directory)
+ let item = self.remember(try self.bridge.item(["op": "create", "parent": parent.identity, "name": name, "directory": type == .directory]))
+ parent.metadata = try self.bridge.item(["op": "node", "node": parent.identity])
+ return try self.checked(FSCreateItemResult(newItem: item, newItemName: FSFileName(string: item.metadata.name), newItemAttributes: self.attrs(item), directoryAttributes: self.attrs(parent), freeSpace: nil))
+ }, replyHandler)
+ }
+ func removeItem(_ raw: FSItem, named name: FSFileName, from directory: FSItem, context: FSContext, replyHandler: @escaping (FSRemoveItemResult?, Error?) -> Void) {
+ perform({
+ let item = try self.item(raw), parent = try self.item(directory)
+ try self.bridge.call(["op": "remove", "node": item.identity])
+ parent.metadata = try self.bridge.item(["op": "node", "node": parent.identity])
+ let removed = self.attrs(item)
+ removed.linkCount = 0
+ return try self.checked(FSRemoveItemResult(itemAttributes: removed, directoryAttributes: self.attrs(parent), freeSpace: nil))
+ }, replyHandler)
+ }
+ func renameItem(_ raw: FSItem, inDirectory sourceDirectory: FSItem, named sourceName: FSFileName, to destinationName: FSFileName, inDirectory destinationDirectory: FSItem, overItem: FSItem?, context: FSContext, replyHandler: @escaping (FSRenameItemResult?, Error?) -> Void) {
+ perform({
+ guard let name = destinationName.string else { throw POSIXError(.EINVAL) }
+ try self.bridge.call(["op": "rename", "node": self.item(raw).identity, "parent": self.item(destinationDirectory).identity, "name": name, "replace": overItem != nil])
+ let item = try self.item(raw), source = try self.item(sourceDirectory), destination = try self.item(destinationDirectory)
+ for item in [item, source, destination] { item.metadata = try self.bridge.item(["op": "node", "node": item.identity]) }
+ let replaced = try overItem.map { self.attrs(try self.item($0)) }
+ replaced?.linkCount = 0
+ return try self.checked(FSRenameItemResult(newName: FSFileName(string: name), renamedItemAttributes: self.attrs(item), sourceDirectoryAttributes: self.attrs(source), destinationDirectoryAttributes: self.attrs(destination), overItemAttributes: replaced, freeSpace: nil))
+ }, replyHandler)
+ }
+ func enumerateDirectory(_ raw: FSItem, startingAt cookie: FSDirectoryCookie, verifier: FSDirectoryVerifier, attributes: FSItem.GetAttributesRequest?, packer: FSDirectoryEntryPacker, context: FSContext, replyHandler: @escaping (FSEnumerateDirectoryResult?, Error?) -> Void) {
+ perform({
+ let directory = try self.item(raw)
+ var request: [String: Any] = ["op": "scan", "node": directory.identity, "offset": cookie.rawValue, "limit": 256]
+ let currentVerifier: UInt64
+ if cookie.rawValue == 0 {
+ currentVerifier = self.nextVerifier
+ self.nextVerifier += 1
+ if self.enumerations.count >= 1024, let oldest = self.enumerations.keys.min() {
+ self.enumerations.removeValue(forKey: oldest)
+ }
+ } else {
+ currentVerifier = verifier.rawValue
+ guard let (identity, revision) = self.enumerations[verifier.rawValue], identity == directory.identity else { throw POSIXError(.ESTALE) }
+ request["revision"] = revision
+ }
+ var offset = cookie.rawValue
+ while true {
+ request["offset"] = offset
+ let page = try self.bridge.call(request)
+ guard let revision = page["revision"] as? String, let entries = page["entries"] as? [[String: Any]] else { throw POSIXError(.EIO) }
+ self.enumerations[currentVerifier] = (directory.identity, revision)
+ request["revision"] = revision
+ for value in entries {
+ let item = self.remember(try NativeItem(value))
+ if !packer.packEntry(name: FSFileName(string: item.metadata.name), itemType: item.metadata.directory ? .directory : .file,
+ itemID: FSItem.Identifier(rawValue: item.number)!, nextCookie: FSDirectoryCookie(offset + 1),
+ attributes: self.attrs(item)) { return currentVerifier }
+ offset += 1
+ }
+ if page["next"] is NSNull { break }
+ }
+ return currentVerifier
+ }) { value, error in replyHandler(value.flatMap { FSEnumerateDirectoryResult(verifier: $0) }, error) }
+ }
+ func read(from raw: FSItem, at offset: off_t, length: Int, into buffer: FSMutableFileDataBuffer, replyHandler: @escaping (FSReadFileResult?, Error?) -> Void) {
+ perform({
+ guard offset >= 0, length >= 0 else { throw POSIXError(.EINVAL) }
+ let item = try self.item(raw)
+ try self.refresh(item)
+ let data = try self.bridge.read(node: item.identity, offset: UInt64(offset), length: length)
+ _ = buffer.withUnsafeMutableBytes { target in data.copyBytes(to: target) }
+ do { item.metadata = try self.bridge.item(["op": "node", "node": item.identity]) }
+ catch let error as NativeFailure where error.kind == "NotFound" { /* Retained unlinked read. */ }
+ guard let result = FSReadFileResult(bytesRead: data.count, itemAttributes: self.attrs(item)) else { throw POSIXError(.EIO) }
+ return result
+ }, replyHandler)
+ }
+ private func refresh(_ item: YinYangItem) throws {
+ do { try bridge.call(["op": "refresh", "node": item.identity]) }
+ catch let error as NativeFailure where error.kind == "Busy" || error.kind == "NotFound" { /* Retain dirty or unlinked bytes. */ }
+ }
+ func write(contents: Data, to raw: FSItem, at offset: off_t, replyHandler: @escaping (FSWriteFileResult?, Error?) -> Void) {
+ perform({
+ guard offset >= 0 else { throw POSIXError(.EINVAL) }
+ let item = try self.item(raw)
+ try self.bridge.write(node: item.identity, offset: UInt64(offset), data: contents)
+ item.metadata.size = max(item.metadata.size, UInt64(offset) + UInt64(contents.count))
+ guard let result = FSWriteFileResult(bytesWritten: contents.count, itemAttributes: self.attrs(item), freeSpace: nil) else { throw POSIXError(.EIO) }
+ return result
+ }, replyHandler)
+ }
+ func open(_ raw: FSItem, modes: FSVolume.OpenModes, cacheMode: FSVolume.DataCacheMode, context: FSContext, replyHandler: @escaping (FSOpenItemResult?, Error?) -> Void) {
+ perform({
+ let item = try self.item(raw)
+ self.references[item.identity, default: 0] += 1
+ return FSOpenItemResult(grantedCoherency: .noCache)
+ }, replyHandler)
+ }
+ func upgrade(_ item: FSItem, cacheMode: FSVolume.DataCacheMode, context: FSContext, replyHandler: @escaping (FSUpgradeItemResult?, Error?) -> Void) {
+ replyHandler(FSUpgradeItemResult(grantedCoherency: .noCache), nil)
+ }
+ func close(_ raw: FSItem, context: FSContext, replyHandler: @escaping () -> Void) {
+ queue.async {
+ do {
+ let item = try self.item(raw)
+ let remaining = max(0, self.references[item.identity, default: 1] - 1)
+ self.references[item.identity] = remaining
+ try self.bridge.call(["op": "fsync"])
+ if remaining == 0 { try self.bridge.call(["op": "release", "node": item.identity]) }
+ } catch { self.logger.error("Close retained pending state: \(String(describing: error), privacy: .public)") }
+ replyHandler()
+ }
+ }
+}
diff --git a/platforms/macos/FSKit/Info.plist b/platforms/macos/FSKit/Info.plist
new file mode 100644
index 0000000..7c0408e
--- /dev/null
+++ b/platforms/macos/FSKit/Info.plist
@@ -0,0 +1,40 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+ <key>CFBundleDevelopmentRegion</key>
+ <string>$(DEVELOPMENT_LANGUAGE)</string>
+ <key>CFBundleDisplayName</key>
+ <string>YinYang file system</string>
+ <key>CFBundleExecutable</key>
+ <string>$(EXECUTABLE_NAME)</string>
+ <key>CFBundleIdentifier</key>
+ <string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
+ <key>CFBundleInfoDictionaryVersion</key>
+ <string>6.0</string>
+ <key>CFBundleName</key>
+ <string>$(PRODUCT_NAME)</string>
+ <key>CFBundleShortVersionString</key>
+ <string>1.0</string>
+ <key>CFBundleVersion</key>
+ <string>1</string>
+ <key>EXAppExtensionAttributes</key>
+ <dict>
+ <key>EXExtensionPointIdentifier</key>
+ <string>com.apple.fskit.fsmodule</string>
+ <key>FSActivateOptionSyntax</key>
+ <dict>
+ <key>shortOptions</key>
+ <string></string>
+ </dict>
+ <key>FSRequiresSecurityScopedPathURLResources</key>
+ <true/>
+ <key>FSShortName</key>
+ <string>yinyang</string>
+ <key>FSSupportsBlockResources</key>
+ <false/>
+ <key>FSSupportsPathURLs</key>
+ <true/>
+ </dict>
+</dict>
+</plist>
diff --git a/platforms/macos/Host/App.swift b/platforms/macos/Host/App.swift
new file mode 100644
index 0000000..adba279
--- /dev/null
+++ b/platforms/macos/Host/App.swift
@@ -0,0 +1,36 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+
+import SwiftUI
+import FSKit
+
+@main
+struct YinYangPrototype: App {
+ var body: some Scene {
+ WindowGroup {
+ VStack(alignment: .leading, spacing: 16) {
+ Text("YinYang native prototype").font(.title)
+ Text("Use an isolated directory containing volume.json. Enable the file system extension, then mount it with mount -F -t yinyang SOURCE TARGET.")
+ .textSelection(.enabled)
+ Button("Open File System Extensions") { _ = FSClient.shared.openFileSystemExtensionsSettings() }
+ Text("Experimental: no production support or existing sync folders.").font(.caption)
+ }.padding(24).frame(width: 540)
+ }
+ }
+}
+
diff --git a/platforms/macos/Host/Host.entitlements b/platforms/macos/Host/Host.entitlements
new file mode 100644
index 0000000..95cd70e
--- /dev/null
+++ b/platforms/macos/Host/Host.entitlements
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+<key>com.apple.security.app-sandbox</key><true/>
+</dict></plist>
+
diff --git a/platforms/macos/README.md b/platforms/macos/README.md
new file mode 100644
index 0000000..89971f6
--- /dev/null
+++ b/platforms/macos/README.md
@@ -0,0 +1,60 @@
+# macOS native prototypes
+
+Requires macOS 27, Xcode 27, XcodeGen and the repository Rust toolchain. These
+extensions operate on isolated test volumes only. See
+[the specification](../../specs/macos-frontends.md) for supported semantics.
+
+Build without signing:
+
+```sh
+cargo x macos
+```
+
+Build with a local Developer ID identity and a profile authorizing the FSKit
+module entitlement for `com.xuanwo.yinyang.prototype.fskit`:
+
+```sh
+cargo x macos --identity 'Developer ID Application: NAME (TEAM)' \
+ --team TEAM --fskit-profile 'FSKit profile name'
+```
+
+The result is `target/macos/DerivedData/Build/Products/Debug/YinYang.app`.
+Open the host, enable its filesystem extension in System Settings, and check
+`pluginkit -m -v -i com.xuanwo.yinyang.prototype.fskit` points to this build.
+An older extension with the same identifier must not be used for acceptance.
+
+Create an isolated resource directory with `volume.json` describing an **existing**
+Managed filesystem. Use dedicated test credentials and restrictive file
+permissions; never commit credentials or provisioning profiles.
+
+```json
+{
+ "profile": "minio",
+ "storage": {
+ "endpoint": "http://127.0.0.1:19000",
+ "bucket": "isolated-test-bucket",
+ "root": "isolated-prefix",
+ "region": "us-east-1",
+ "access_key_id": "TEST_KEY",
+ "secret_access_key": "TEST_SECRET"
+ }
+}
+```
+
+The adapter supplies staging beneath the selected resource. Mount into a separate
+empty directory using absolute paths:
+
+```sh
+mount -F -t yinyang /absolute/test-resource /absolute/test-mount
+```
+
+Acceptance must check `mount` reports `yinyang` before and after I/O, and compare
+results with an independent `yy restore` from the same remote filesystem. An
+extension crash can unmount the volume and expose the underlying local directory;
+successful local writes alone do not establish native or remote correctness.
+
+Exercise multiple descriptors, close-one/write-another, fsync, truncate, safe-save
+replacement, directory pagination, independent remote updates, backend outage and
+extension restart with the original staging directory. Do not remove pending
+staging or use an existing user sync directory. Unmount before rebuilding; ensure
+the next launch runs the newly built extension rather than the previous process.
diff --git a/platforms/macos/Shared/NativeBridge.swift b/platforms/macos/Shared/NativeBridge.swift
new file mode 100644
index 0000000..dd7fe9f
--- /dev/null
+++ b/platforms/macos/Shared/NativeBridge.swift
@@ -0,0 +1,109 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+
+import Foundation
+
+struct NativeFailure: Error {
+ let kind: String
+ let message: String
+ var posix: Error {
+ let code: POSIXErrorCode
+ switch kind {
+ case "NotFound": code = .ENOENT
+ case "AlreadyExists": code = .EEXIST
+ case "NotDirectory": code = .ENOTDIR
+ case "IsDirectory": code = .EISDIR
+ case "NotEmpty": code = .ENOTEMPTY
+ case "ReadOnly": code = .EROFS
+ case "PermissionDenied": code = .EACCES
+ case "Busy", "Frozen": code = .EBUSY
+ case "Conflict", "Retryable": code = .EAGAIN
+ case "Invalid", "InvalidName": code = .EINVAL
+ case "Unsupported": code = .ENOTSUP
+ case "NoSpace": code = .ENOSPC
+ case "TooLarge": code = .EFBIG
+ default: code = .EIO
+ }
+ return POSIXError(code)
+ }
+}
+struct NativeItem: Decodable {
+ let node: String
+ let parent: String?
+ let name: String
+ let directory: Bool
+ var size: UInt64
+ let executable: Bool
+ let generation: UInt64
+ let revision: String
+ init(_ value: [String: Any]) throws {
+ self = try JSONDecoder().decode(Self.self, from: JSONSerialization.data(withJSONObject: value))
+ }
+}
+final class NativeBridge {
+ private let session: UInt64
+ static func invoke(_ value: [String: Any]) throws -> [String: Any] {
+ let input = try JSONSerialization.data(withJSONObject: value)
+ let output = input.withUnsafeBytes {
+ yy_native_call($0.baseAddress?.assumingMemoryBound(to: UInt8.self), $0.count)
+ }
+ guard let output else { throw POSIXError(.ENOMEM) }
+ defer { yy_native_free(output) }
+ let result = try JSONSerialization.jsonObject(with: Data(String(cString: output).utf8)) as? [String: Any]
+ if let error = result?["error"] as? [String: Any] {
+ throw NativeFailure(kind: error["kind"] as? String ?? "Io",
+ message: error["message"] as? String ?? "Native operation failed")
+ }
+ guard let ok = result?["ok"] as? [String: Any] else { throw POSIXError(.EIO) }
+ return ok
+ }
+ init(config: [String: Any], mode: String) throws {
+ let result = try Self.invoke(["action": "connect", "config": config, "mode": mode])
+ guard let id = result["session"] as? NSNumber else { throw POSIXError(.EIO) }
+ session = id.uint64Value
+ }
+ deinit { _ = try? Self.invoke(["action": "close", "session": session]) }
+ @discardableResult
+ func call(_ request: [String: Any]) throws -> [String: Any] {
+ try Self.invoke(["action": "call", "session": session, "request": request])
+ }
+ func item(_ request: [String: Any]) throws -> NativeItem { try NativeItem(call(request)) }
+ func read(node: String, offset: UInt64, length: Int, revision: String? = nil) throws -> Data {
+ var output = Data()
+ while output.count < length {
+ let count = min(length - output.count, 1024 * 1024)
+ var request: [String: Any] = ["op": revision == nil ? "read" : "download",
+ "node": node, "offset": offset + UInt64(output.count), "length": count]
+ if let revision { request["revision"] = revision }
+ let response = try call(request)
+ guard let bytes = response["bytes"] as? [UInt8] else { throw POSIXError(.EIO) }
+ output.append(contentsOf: bytes)
+ if bytes.count < count { break }
+ }
+ return output
+ }
+ func write(node: String, offset: UInt64, data: Data) throws {
+ var position = 0
+ while position < data.count {
+ let end = min(position + 1024 * 1024, data.count)
+ try call(["op": "write", "node": node, "offset": offset + UInt64(position),
+ "bytes": Array(data[position..<end])])
+ position = end
+ }
+ }
+}
diff --git a/platforms/macos/project.yml b/platforms/macos/project.yml
new file mode 100644
index 0000000..53ae715
--- /dev/null
+++ b/platforms/macos/project.yml
@@ -0,0 +1,63 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+name: YinYang
+options:
+ deploymentTarget:
+ macOS: "27.0"
+settings:
+ base:
+ SWIFT_VERSION: "5.0"
+ CODE_SIGN_STYLE: Manual
+ CODE_SIGN_IDENTITY: "-"
+ MACOSX_DEPLOYMENT_TARGET: "27.0"
+ ENABLE_HARDENED_RUNTIME: YES
+ GENERATE_INFOPLIST_FILE: YES
+ SWIFT_EMIT_LOC_STRINGS: NO
+ CURRENT_PROJECT_VERSION: "1"
+ MARKETING_VERSION: "1.0"
+targets:
+ YinYang:
+ type: application
+ platform: macOS
+ sources: [Host]
+ settings:
+ base:
+ PRODUCT_BUNDLE_IDENTIFIER: com.xuanwo.yinyang.prototype
+ CODE_SIGN_ENTITLEMENTS: "$(YINYANG_SOURCE_ROOT)/platforms/macos/Host/Host.entitlements"
+ INFOPLIST_KEY_CFBundleDisplayName: YinYang Prototype
+ PROVISIONING_PROFILE_SPECIFIER: ""
+ dependencies:
+ - target: YinYangFSKit
+ embed: true
+ YinYangFSKit:
+ type: extensionkit-extension
+ platform: macOS
+ sources: [Shared, FSKit]
+ settings:
+ base:
+ PRODUCT_BUNDLE_IDENTIFIER: com.xuanwo.yinyang.prototype.fskit
+ INFOPLIST_FILE: "$(YINYANG_SOURCE_ROOT)/platforms/macos/FSKit/Info.plist"
+ CODE_SIGN_ENTITLEMENTS: "$(YINYANG_SOURCE_ROOT)/platforms/macos/FSKit/FSKit.entitlements"
+ PROVISIONING_PROFILE_SPECIFIER: "$(YINYANG_FSKIT_PROFILE)"
+ SWIFT_OBJC_BRIDGING_HEADER: "$(YINYANG_BRIDGING_HEADER)"
+ OTHER_LDFLAGS: ["$(inherited)", "$(YINYANG_NATIVE_LIBRARY)", "-framework", Security, "-framework", SystemConfiguration, "-lc++"]
+schemes:
+ YinYang:
+ build:
+ targets:
+ YinYang: all
diff --git a/specs/README.md b/specs/README.md
index e60005d..7d2ff38 100644
--- a/specs/README.md
+++ b/specs/README.md
@@ -12,6 +12,7 @@ This directory contains the maintained contracts for Apache OpenDALâ„¢ YinYang.
| [Mount runtime](mount-runtime.md) | Instance-local shared nodes, explicit refresh, remote fsync, and retained failures. |
| [Sync runtime](sync-runtime.md) | Baseline-bound local edits, conditional publication, conflict retention, and exact retry. |
| [Native bridge](native-bridge.md) | In-process ownership and private adapter request semantics. |
+| [Experimental macOS frontends](macos-frontends.md) | Native FSKit and File Provider integration boundaries. |
| [Volume capabilities](volume-capabilities.md) | Configuration, four-layer admission, read-only enforcement, and CLI status. |
| [Transactional filesystem](transactional-filesystem.md) | Shared target contract. Object-storage and metadata-service bindings implemented experimentally. |
diff --git a/specs/macos-frontends.md b/specs/macos-frontends.md
new file mode 100644
index 0000000..be66245
--- /dev/null
+++ b/specs/macos-frontends.md
@@ -0,0 +1,49 @@
+# Experimental macOS frontends
+
+**Status: prototypes on macOS 27 / Xcode 27, not production volume support.**
+
+The adapters link `yinyang-native` and use the same Authority, Mount and Sync
+coordinators as library callers. `cargo x macos` builds a host and an FSKit
+extension. Signing and OS registration are explicit operator actions, not build
+side effects. Neither adapter initializes or reformats remote storage.
+
+## FSKit Mount
+
+The FSKit path resource is an explicitly selected directory containing
+`volume.json`; durable staging is its `mount-state` child. The extension obtains
+the security-scoped resource before reading either.
+
+The volume uses core NodeIds internally and stable volume-lifetime numeric inode
+IDs at the kernel boundary. Directory verifiers retain an immutable revision;
+cookies are ordinal positions, not live-list offsets. At most 1024 enumerations
+are retained; an evicted verifier returns ESTALE. The item identity map currently
+lives until unmount and is not a large-tree memory scalability claim.
+
+All filesystem callbacks serialize off the main thread. DataCacheHandler grants
+`noCache`; clean reads refresh the shared Mount node, while dirty and unlinked
+nodes retain staged bytes. This favors correctness over read performance and
+does not claim mmap, kernel-cache invalidation or a distributed POSIX cache.
+The macOS 27 read/write result objects carry updated attributes back to FSKit.
+
+**Concurrent external length changes are not supported by this prototype.** On
+the tested macOS 27 build, the kernel can retain the old EOF despite newer
+attributes returned by read/get-attributes handlers. Data-cache invalidation alone
+does not establish metadata coherence. Remount before consuming externally
+resized files. This is an acceptance blocker for multi-client writable Mount;
+the uncached data path alone is not evidence that this contract is satisfied.
+
+Reads, writes, truncate, create, mkdir, unlink, rmdir, enumeration and atomic
+replace rename use the real runtime. Volume synchronization publishes staged
+content and propagates errors. The non-reporting close callback attempts fsync,
+logs a failure and retains staged state; close is not an error-reporting durability
+boundary. Recovery reopens the same staging directory and original frozen request.
+
+Ownership and modes are synthesized (current uid/gid, files 0644 or 0755 according
+to the core executable flag, directories 0755). Creation does not persist requested
+permissions. Timestamps encode generation, not wall-clock times. Permission and
+timestamp changes, links and extended attributes are unsupported. There is no
+disk capacity claim. Unsupported metadata is not marked consumed.
+
+There is no conflict-resolution UI. Retained failures and bytes remain in the
+runtime staging journal; operators must not delete that directory to recover a
+failed write.
diff --git a/xtask/src/main.rs b/xtask/src/main.rs
index 94f97ea..5e41ceb 100644
--- a/xtask/src/main.rs
+++ b/xtask/src/main.rs
@@ -41,6 +41,7 @@ impl Command {
SubCommand::Licenses(cmd) => cmd.run(),
SubCommand::Lint(cmd) => cmd.run(),
SubCommand::Test(cmd) => cmd.run(),
+ SubCommand::Macos(cmd) => cmd.run(),
}
}
}
@@ -55,6 +56,78 @@ enum SubCommand {
Lint(CommandLint),
#[clap(about = "Run all workspace tests.")]
Test(CommandTest),
+ #[clap(about = "Build the macOS native prototypes (requires Xcode 27 and XcodeGen).")]
+ Macos(CommandMacos),
+}
+
+#[derive(Parser)]
+struct CommandMacos {
+ #[arg(long, default_value = "target/macos")]
+ output: std::path::PathBuf,
+ #[arg(long, requires_all = ["team", "fskit_profile"])]
+ identity: Option<String>,
+ #[arg(long, requires = "identity")]
+ team: Option<String>,
+ #[arg(long, requires = "identity")]
+ fskit_profile: Option<String>,
+}
+impl CommandMacos {
+ fn run(self) {
+ if !cfg!(target_os = "macos") {
+ panic!("native macOS build requires macOS");
+ }
+ let root = std::path::Path::new(env!("CARGO_WORKSPACE_DIR"));
+ let output = root.join(self.output);
+ let target =
+ root.join(std::env::var_os("CARGO_TARGET_DIR").unwrap_or_else(|| "target".into()));
+ let mut cargo = find_command("cargo");
+ cargo.args(["build", "-p", "yinyang-native"]);
+ run_command(cargo);
+ std::fs::create_dir_all(&output).expect("create native build directory");
+ let mut generate = find_command("xcodegen");
+ generate.args([
+ "generate",
+ "--spec",
+ "platforms/macos/project.yml",
+ "--project",
+ ]);
+ generate.arg(&output);
+ run_command(generate);
+ let mut build = find_command("xcodebuild");
+ build.arg("-project").arg(output.join("YinYang.xcodeproj"));
+ build.args([
+ "-scheme",
+ "YinYang",
+ "-configuration",
+ "Debug",
+ "-derivedDataPath",
+ ]);
+ build.arg(output.join("DerivedData"));
+ build.args(["-destination", "platform=macOS", "build"]);
+ build.arg(format!("YINYANG_SOURCE_ROOT={}", root.display()));
+ build.arg(format!(
+ "YINYANG_NATIVE_LIBRARY={}",
+ target.join("debug/libyinyang_native.a").display()
+ ));
+ build.arg(format!(
+ "YINYANG_BRIDGING_HEADER={}",
+ root.join("crates/native/include/yinyang.h").display()
+ ));
+ if let Some(identity) = self.identity {
+ build.arg(format!("CODE_SIGN_IDENTITY={identity}"));
+ build.arg(format!(
+ "DEVELOPMENT_TEAM={}",
+ self.team.expect("team required")
+ ));
+ build.arg(format!(
+ "YINYANG_FSKIT_PROFILE={}",
+ self.fskit_profile.expect("profile required")
+ ));
+ } else {
+ build.arg("CODE_SIGNING_ALLOWED=NO");
+ }
+ run_command(build);
+ }
}
#[derive(Parser)]