openvfs-rb 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4e4e0c990813542ab1b0b2aee640ffe25e13b865ec89300f22e796a37251f37f
+  data.tar.gz: 618bec06ee55f463316af80cb2cfad9e02b21a66748629d070d087c6dc2a645f
+SHA512:
+  metadata.gz: 11ec8556f9b9e44533591404eee4ffc900b2a615918972f9d8be968741ec13123a8de10d2cf49509ed98cf35b82cb8beda73c675867926666e6076401537e803
+  data.tar.gz: 9988ae322baa3fbd3a71edabe1db176f025172fb2ff4477714df88bff8942e4e6f2bc4bf1cbae14cf4ba25c686208482fc312346b753d632ec1af3fd557f1bb3

data/README.md

@@ -0,0 +1,97 @@
+# openvfs-rb
+
+A virtual filesystem for Ruby.
+
+```ruby
+gem "openvfs-rb"
+```
+
+```ruby
+require "openvfs"
+
+OpenVFS::VERSION
+```
+
+## OpenVFS API
+
+The native extension wraps OpenVFS's registration and placeholder metadata
+types:
+
+```ruby
+registration = OpenVFS::Registration.register_filesystem(path, owner)
+raise registration.error unless registration.ok?
+
+attributes = OpenVFS::PlaceHolderAttributes.create(path, etag, file_id, size)
+attributes.state = OpenVFS::Constants::States::DeHydrated
+serialized_attributes = attributes.to_data
+```
+
+OpenVFS development headers and `libopenvfs` are required to build the
+extension. In this repository's Nix development shell they are provided by the
+locked OpenVFS source input.
+
+## OpenCloud Desktop sync client
+
+`OpenVFS` wraps the desktop client's account and keychain. Configure a folder, store the account's credential, then run the client:
+
+```ruby
+require "openvfs/occ"
+
+uuid = OpenVFS.configure(
+  "/local/folder",
+  url: "https://cloud.example",
+  remote_path: "/remote.php/dav/files/user",
+)
+
+account = OpenVFS::Account.create(uuid)
+account.url = "https://cloud.example"
+account.credential_manager.set("http/oauthtoken", ENV.fetch("OPENCLOUD_ACCESS_TOKEN"))
+
+OpenVFS.start(["--logfile", "-"])
+```
+
+`OpenVFS.configure` writes `~/.config/openvfs-rb/openvfs-rb.cfg`; it does not touch the keychain. `OpenVFS::Account.create` returns the wrapped account, `account.url=` sets the server, and `account.credential_manager` exposes `set`, `get`, `remove` and `contains?`. The keychain methods block until QtKeychain's job finishes, so no event loop needs to be running. For a server that enables HTTP Basic authentication, store the complete `Basic ...` header instead of a bearer token. `OpenVFS.start` calls the desktop's `OCC::init`, which runs the sync client's event loop and does not return until the client exits; run it in its own process.
+
+### Building the desktop subset
+
+The locked `desktop` flake input is built into a small static library with Qt's generated meta-object code, using the patches under `patches/`. The patches keep the sync engine and keychain, and omit the desktop UI, QML, translations and unrelated plugins.
+
+```sh
+nix develop --command ruby -C ext/openvfs extconf.rb
+nix develop --command make -C ext/openvfs
+nix develop --command ruby -C ext/openvfs/occ extconf.rb
+nix develop --command make -C ext/openvfs/occ
+nix develop --command bundle exec sus
+```
+
+The development shell provides `OPENCLOUD_UPLOAD_PREFIX` and `pkg-config`
+metadata. Outside the shell, install that subset and its Qt 6 development
+dependencies, then make `opencloud-upload.pc` visible to `pkg-config`.
+The installed `opencloud-upload.pc`, headers and static library are what the extension builds against.
+
+### Local OpenCloud server
+
+The integration test in `test/openvfs/sync.rb` configures a temporary local folder, starts the client, and checks that a file dropped into the folder reaches a real OpenCloud server.
+
+The test skips while no server answers `OPENCLOUD_URL`, so the default run stays hermetic.
+
+```sh
+docker compose up -d opencloud
+nix develop --command bundle exec sus test/openvfs/sync.rb
+```
+
+The compose file starts `opencloudeu/opencloud-rolling:9.0.0` with WebDAV basic
+authentication enabled and listens on `127.0.0.1:${OPENCLOUD_PORT:-18280}`.
+Override the credentials with `OPENCLOUD_USER` and `OPENCLOUD_PASSWORD` when the default admin user is not the account you want to sync.
+
+## Contributing
+
+See [RELEASE.md](RELEASE.md) for the release process and
+[DEPRECATIONS.md](DEPRECATIONS.md) for the deprecation policy.
+
+## License
+
+Released under the [MIT License](license.md).
+
+The linked OpenCloud Desktop sources retain their upstream GPL/LGPL licenses;
+the subset derivation installs the upstream `COPYING` file with the library.

data/ext/openvfs/extconf.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "mkmf-rice"
+
+prefix = ENV.fetch("OPENVFS_PREFIX") do
+  abort "OPENVFS_PREFIX must point to the OpenVFS installation prefix"
+end
+
+openvfs_include_dir = File.join(prefix, "include")
+openvfs_library_dir = File.join(prefix, "lib")
+
+dir_config("openvfs", openvfs_include_dir, openvfs_library_dir)
+$CXXFLAGS << " -std=c++23 -Wno-array-bounds -ftemplate-backtrace-limit=0"
+$LDFLAGS << " -Wl,-rpath,#{openvfs_library_dir}"
+
+unless have_header("openvfs/openvfs.h")
+  abort "missing OpenVFS headers"
+end
+
+unless have_library("openvfs")
+  abort "missing libopenvfs"
+end
+
+create_makefile "openvfs/openvfs"

data/ext/openvfs/occ/extconf.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "mkmf-rice"
+
+if ENV.key?("OPENCLOUD_UPLOAD_PREFIX")
+  pkg_config_path = File.join(ENV.fetch("OPENCLOUD_UPLOAD_PREFIX"), "lib", "pkgconfig")
+  ENV["PKG_CONFIG_PATH"] = [pkg_config_path, ENV["PKG_CONFIG_PATH"]].compact.join(File::PATH_SEPARATOR)
+end
+
+unless pkg_config("opencloud-upload")
+  abort "missing opencloud-upload development files; enter nix develop or set OPENCLOUD_UPLOAD_PREFIX"
+end
+
+$CXXFLAGS << " -std=c++23 -fPIC -Wno-array-bounds"
+
+# The static library is built with -ffunction-sections, so the link can drop every function the extension never calls. ld64 spells that -dead_strip and has no equivalent of --exclude-libs.
+if RbConfig::CONFIG["host_os"].match?(/darwin/)
+  $LDFLAGS << " -Wl,-dead_strip"
+else
+  $LDFLAGS << " -Wl,--gc-sections -Wl,--exclude-libs,ALL"
+end
+
+# opencloudsynclib.h rather than a real header: mkmf puts ruby.h first in the program it compiles to probe, and on Windows that defines truncate and access as macros, which Qt refuses to be parsed after. The generated export header pulls in nothing, so it answers the only question being asked - whether the development files are installed.
+unless have_header("libsync/opencloudsynclib.h")
+  abort "missing OpenCloud Desktop upload headers"
+end
+
+create_makefile "openvfs/occ/occ"

data/ext/openvfs/occ/sync.cpp

@@ -0,0 +1,502 @@
+// Rice bindings for OpenCloud Desktop.
+//
+// Only two classes are wrapped: OCC::Account and OCC::CredentialManager, plus the types
+// their methods take and return, and OCC::init - the desktop's own entry point, with the
+// UI patched out. Nothing here adds behaviour that libsync does not already have.
+//
+// is_convertible returns a double score, matching Rice 4.12.0's own converters in
+// stl.hpp; Rice's published docs still describe an older enum form.
+
+// Qt comes before Ruby, and the order is load-bearing on Windows: ruby.h defines truncate and access as macros onto its own win32 replacements, and Qt's headers stop with an #error rather than be parsed after that.
+#include <libsync/account.h>
+#include <libsync/creds/credentialmanager.h>
+
+#include <qt6keychain/keychain.h>
+
+#include <QCoreApplication>
+#include <QEventLoop>
+#include <QString>
+#include <QStringList>
+#include <QUrl>
+#include <QTimer>
+#include <QUuid>
+#include <QVariant>
+
+// rice.hpp uses std::exception_ptr, std::sort and std::count_if without including the headers that define them. libstdc++ happens to pull them in anyway; libc++ does not, so on clang exception_ptr is incomplete and the algorithms are missing unless these come first.
+#include <algorithm>
+#include <exception>
+
+#include <rice/rice.hpp>
+#include <rice/stl.hpp>
+
+#include <memory>
+
+namespace OCC {
+// Defined in src/gui/main.cpp, which the patches reduce to the non-UI bootstrap.
+int init(const QStringList &arguments);
+}
+
+// ---------------------------------------------------------------------------------------------
+// Type converters: Rice ships these for fundamental types and the STL, so Qt's own need
+// the three documented steps - specialize Type, To_Ruby and From_Ruby.
+// ---------------------------------------------------------------------------------------------
+
+namespace Rice::detail
+{
+    template<>
+    struct Type<QString>
+    {
+        static bool verify() { return true; }
+    };
+
+    template<>
+    class To_Ruby<QString>
+    {
+    public:
+        To_Ruby() = default;
+        explicit To_Ruby(Arg* arg) : arg_(arg) { }
+
+        VALUE convert(const QString& string)
+        {
+            const QByteArray utf8 = string.toUtf8();
+            return String(std::string(utf8.constData(), utf8.size())).value();
+        }
+
+    private:
+        Arg* arg_ = nullptr;
+    };
+
+    template<>
+    class From_Ruby<QString>
+    {
+    public:
+        From_Ruby() = default;
+        explicit From_Ruby(Arg* arg) : arg_(arg) { }
+
+        double is_convertible(VALUE value)
+        {
+            return rb_type(value) == RUBY_T_STRING ? Convertible::Exact : Convertible::None;
+        }
+
+        QString convert(VALUE value)
+        {
+            const std::string string = From_Ruby<std::string>().convert(value);
+            return QString::fromUtf8(string.data(), static_cast<qsizetype>(string.size()));
+        }
+
+    private:
+        Arg* arg_ = nullptr;
+    };
+
+    template<>
+    struct Type<QStringList>
+    {
+        static bool verify() { return Type<QString>::verify(); }
+    };
+
+    template<>
+    class To_Ruby<QStringList>
+    {
+    public:
+        To_Ruby() = default;
+        explicit To_Ruby(Arg* arg) : arg_(arg) { }
+
+        VALUE convert(const QStringList& strings)
+        {
+            Array result;
+            for (const QString& string : strings) {
+                result.push(string, true);
+            }
+            return result.value();
+        }
+
+    private:
+        Arg* arg_ = nullptr;
+    };
+
+    template<>
+    class From_Ruby<QStringList>
+    {
+    public:
+        From_Ruby() = default;
+        explicit From_Ruby(Arg* arg) : arg_(arg) { }
+
+        double is_convertible(VALUE value)
+        {
+            return rb_type(value) == RUBY_T_ARRAY ? Convertible::Exact : Convertible::None;
+        }
+
+        QStringList convert(VALUE value)
+        {
+            Array array(value);
+            QStringList result;
+            for (long i = 0; i < array.size(); i++) {
+                result.append(From_Ruby<QString>().convert(array[i].value()));
+            }
+            return result;
+        }
+
+    private:
+        Arg* arg_ = nullptr;
+    };
+
+    template<>
+    struct Type<QUrl>
+    {
+        static bool verify() { return true; }
+    };
+
+    template<>
+    class To_Ruby<QUrl>
+    {
+    public:
+        To_Ruby() = default;
+        explicit To_Ruby(Arg* arg) : arg_(arg) { }
+
+        VALUE convert(const QUrl& url) { return To_Ruby<QString>().convert(url.toString()); }
+
+    private:
+        Arg* arg_ = nullptr;
+    };
+
+    template<>
+    class From_Ruby<QUrl>
+    {
+    public:
+        From_Ruby() = default;
+        explicit From_Ruby(Arg* arg) : arg_(arg) { }
+
+        double is_convertible(VALUE value)
+        {
+            return rb_type(value) == RUBY_T_STRING ? Convertible::Exact : Convertible::None;
+        }
+
+        QUrl convert(VALUE value) { return QUrl(From_Ruby<QString>().convert(value)); }
+
+    private:
+        Arg* arg_ = nullptr;
+    };
+
+    template<>
+    struct Type<QUuid>
+    {
+        static bool verify() { return true; }
+    };
+
+    template<>
+    class To_Ruby<QUuid>
+    {
+    public:
+        To_Ruby() = default;
+        explicit To_Ruby(Arg* arg) : arg_(arg) { }
+
+        VALUE convert(const QUuid& uuid)
+        {
+            return To_Ruby<QString>().convert(uuid.toString(QUuid::WithoutBraces));
+        }
+
+    private:
+        Arg* arg_ = nullptr;
+    };
+
+    template<>
+    class From_Ruby<QUuid>
+    {
+    public:
+        From_Ruby() = default;
+        explicit From_Ruby(Arg* arg) : arg_(arg) { }
+
+        double is_convertible(VALUE value)
+        {
+            return rb_type(value) == RUBY_T_STRING ? Convertible::Exact : Convertible::None;
+        }
+
+        QUuid convert(VALUE value) { return QUuid::fromString(From_Ruby<QString>().convert(value)); }
+
+    private:
+        Arg* arg_ = nullptr;
+    };
+
+    // CredentialManager::set stores a QVariant and CredentialJob::data returns one.
+    template<>
+    struct Type<QVariant>
+    {
+        static bool verify() { return true; }
+    };
+
+    template<>
+    class To_Ruby<QVariant>
+    {
+    public:
+        To_Ruby() = default;
+        explicit To_Ruby(Arg* arg) : arg_(arg) { }
+
+        VALUE convert(const QVariant& variant)
+        {
+            if (!variant.isValid()) {
+                return Qnil;
+            }
+            switch (variant.typeId()) {
+                case QMetaType::Bool:
+                    return variant.toBool() ? Qtrue : Qfalse;
+                case QMetaType::Int:
+                case QMetaType::UInt:
+                case QMetaType::LongLong:
+                case QMetaType::ULongLong:
+                    return To_Ruby<long long>().convert(variant.toLongLong());
+                case QMetaType::Double:
+                    return To_Ruby<double>().convert(variant.toDouble());
+                default:
+                    return To_Ruby<QString>().convert(variant.toString());
+            }
+        }
+
+    private:
+        Arg* arg_ = nullptr;
+    };
+
+    template<>
+    class From_Ruby<QVariant>
+    {
+    public:
+        From_Ruby() = default;
+        explicit From_Ruby(Arg* arg) : arg_(arg) { }
+
+        double is_convertible(VALUE value)
+        {
+            switch (rb_type(value)) {
+                case RUBY_T_STRING:
+                case RUBY_T_FIXNUM:
+                case RUBY_T_BIGNUM:
+                case RUBY_T_FLOAT:
+                case RUBY_T_TRUE:
+                case RUBY_T_FALSE:
+                case RUBY_T_NIL:
+                    return Convertible::Exact;
+                default:
+                    return Convertible::None;
+            }
+        }
+
+        QVariant convert(VALUE value)
+        {
+            switch (rb_type(value)) {
+                case RUBY_T_NIL:
+                    return QVariant();
+                case RUBY_T_TRUE:
+                    return QVariant(true);
+                case RUBY_T_FALSE:
+                    return QVariant(false);
+                case RUBY_T_FIXNUM:
+                case RUBY_T_BIGNUM:
+                    return QVariant(From_Ruby<long long>().convert(value));
+                case RUBY_T_FLOAT:
+                    return QVariant(From_Ruby<double>().convert(value));
+                default:
+                    return QVariant(From_Ruby<QString>().convert(value));
+            }
+        }
+
+    private:
+        Arg* arg_ = nullptr;
+    };
+
+    // Rice matches converters on the exact parameter type, so `const T&` parameters need
+    // their own; each stores the converted value and returns a reference to it.
+    template<typename T>
+    class From_Ruby_Qt_Ref
+    {
+    public:
+        From_Ruby_Qt_Ref() = default;
+        explicit From_Ruby_Qt_Ref(Arg* arg) : arg_(arg) { }
+
+        double is_convertible(VALUE value) { return From_Ruby<T>(this->arg_).is_convertible(value); }
+
+        T& convert(VALUE value)
+        {
+            this->converted_ = From_Ruby<T>(this->arg_).convert(value);
+            return this->converted_;
+        }
+
+    private:
+        Arg* arg_ = nullptr;
+        T converted_;
+    };
+
+    template<>
+    class From_Ruby<QString&> : public From_Ruby_Qt_Ref<QString>
+    {
+    public:
+        using From_Ruby_Qt_Ref<QString>::From_Ruby_Qt_Ref;
+    };
+
+    template<>
+    class From_Ruby<QUrl&> : public From_Ruby_Qt_Ref<QUrl>
+    {
+    public:
+        using From_Ruby_Qt_Ref<QUrl>::From_Ruby_Qt_Ref;
+    };
+
+    template<>
+    class From_Ruby<QUuid&> : public From_Ruby_Qt_Ref<QUuid>
+    {
+    public:
+        using From_Ruby_Qt_Ref<QUuid>::From_Ruby_Qt_Ref;
+    };
+
+    template<>
+    class From_Ruby<QVariant&> : public From_Ruby_Qt_Ref<QVariant>
+    {
+    public:
+        using From_Ruby_Qt_Ref<QVariant>::From_Ruby_Qt_Ref;
+    };
+
+    template<>
+    class From_Ruby<QStringList&> : public From_Ruby_Qt_Ref<QStringList>
+    {
+    public:
+        using From_Ruby_Qt_Ref<QStringList>::From_Ruby_Qt_Ref;
+    };
+}
+
+using namespace Rice;
+
+namespace {
+constexpr int keychainTimeoutMsC = 30000;
+
+// QtKeychain queues its work onto the Qt event loop. Before OpenVFS.start there is no
+// loop, so a credential operation creates a temporary application, runs the job to
+// completion, and tears the application down again.
+class ApplicationScope
+{
+public:
+    ApplicationScope()
+    {
+        if (QCoreApplication::instance()) {
+            return;
+        }
+
+        static int argc = 1;
+        static char name[] = "openvfs-rb";
+        static char *argv[] = {name, nullptr};
+        _application = std::make_unique<QCoreApplication>(argc, argv);
+        _application->setApplicationName(QStringLiteral("openvfs-rb"));
+    }
+
+    ~ApplicationScope()
+    {
+        if (!_application) {
+            return;
+        }
+
+        _application.reset();
+        // QCoreApplication clears the application name when it is destroyed.
+        QCoreApplication::setApplicationName(QStringLiteral("openvfs-rb"));
+    }
+
+private:
+    std::unique_ptr<QCoreApplication> _application;
+};
+
+bool wait_for(QKeychain::Job *job)
+{
+    QEventLoop loop;
+    QObject::connect(job, &QKeychain::Job::finished, &loop, &QEventLoop::quit);
+    QTimer::singleShot(keychainTimeoutMsC, &loop, &QEventLoop::quit);
+    loop.exec();
+
+    return job->error() == QKeychain::NoError;
+}
+
+bool credential_set(OCC::CredentialManager &manager, const QString &key, const QVariant &data)
+{
+    if (!data.isValid()) {
+        return false;
+    }
+
+    ApplicationScope application;
+    return wait_for(manager.set(key, data));
+}
+
+bool credential_remove(OCC::CredentialManager &manager, const QString &key)
+{
+    ApplicationScope application;
+    if (!manager.contains(key)) {
+        return false;
+    }
+
+    return wait_for(manager.remove(key));
+}
+
+bool credential_contains(const OCC::CredentialManager &manager, const QString &key)
+{
+    ApplicationScope application;
+    return manager.contains(key);
+}
+
+QVariant credential_get(OCC::CredentialManager &manager, const QString &key)
+{
+    ApplicationScope application;
+    auto *job = manager.get(key);
+
+    QEventLoop loop;
+    QObject::connect(job, &OCC::CredentialJob::finished, &loop, &QEventLoop::quit);
+    QTimer::singleShot(keychainTimeoutMsC, &loop, &QEventLoop::quit);
+    loop.exec();
+
+    if (job->error() != QKeychain::NoError) {
+        return {};
+    }
+
+    return job->data();
+}
+}
+
+extern "C" void Init_occ()
+{
+    Rice::detail::cpp_protect([] {
+        QCoreApplication::setApplicationName(QStringLiteral("openvfs-rb"));
+
+        Module rb_mOpenVFS = define_module("OpenVFS");
+
+        // -----------------------------------------------------------------------------------------
+        // The desktop's entry point: src/gui/main.cpp, reduced by the patches to its non-UI
+        // bootstrap. It takes the arguments the command line already accepts.
+        // -----------------------------------------------------------------------------------------
+
+        rb_mOpenVFS.define_module_function(
+            "start",
+            [](const QStringList &arguments) {
+                return OCC::init(QStringList{QStringLiteral("openvfs-rb")} + arguments);
+            },
+            Arg("arguments") = QStringList{});
+
+        // -----------------------------------------------------------------------------------------
+        // OCC::CredentialManager - the account's keychain. Each operation runs the keychain job
+        // to completion, so Ruby never sees a Qt job object.
+        // -----------------------------------------------------------------------------------------
+
+        Data_Type<OCC::CredentialManager> rb_cCredentialManager =
+            define_class_under<OCC::CredentialManager>(rb_mOpenVFS, "CredentialManager")
+            .define_method("set", &credential_set, Arg("key"), Arg("data"))
+            .define_method("get", &credential_get, Arg("key"))
+            .define_method("remove", &credential_remove, Arg("key"))
+            .define_method("contains?", &credential_contains, Arg("key"));
+
+        // -----------------------------------------------------------------------------------------
+        // OCC::Account - one configured server connection.
+        // -----------------------------------------------------------------------------------------
+
+        // Account::create hands back a QSharedPointer, and every libsync class takes one.
+        // Wrapping the pointer itself - rather than what it points at - is what keeps the
+        // reference count alive while Ruby holds it.
+        Data_Type<OCC::AccountPtr> rb_cAccount =
+            define_class_under<OCC::AccountPtr>(rb_mOpenVFS, "Account")
+            .define_singleton_function("create", &OCC::Account::create, Arg("uuid"))
+            .define_method("uuid", [](const OCC::AccountPtr &self) { return self->uuid(); })
+            .define_method("url", [](const OCC::AccountPtr &self) { return self->url(); })
+            .define_method("url=", [](OCC::AccountPtr &self, const QUrl &url) { self->setUrl(url); }, Arg("url"))
+            .define_method("credential_manager", [](const OCC::AccountPtr &self) { return self->credentialManager(); },
+                Return().keepAlive());
+    });
+}

data/ext/openvfs/ruby_openvfs.cpp

@@ -0,0 +1,113 @@
+// rice.hpp uses std::exception_ptr, std::sort and std::count_if without including the headers that define them. libstdc++ happens to pull them in anyway; libc++ does not, so on clang exception_ptr is incomplete and the algorithms are missing unless these come first.
+#include <algorithm>
+#include <exception>
+
+#include <rice/rice.hpp>
+#include <rice/stl.hpp>
+
+#include <openvfs/openvfs.h>
+#include <openvfs/openvfconstants.h>
+
+#include <cstdint>
+#include <filesystem>
+#include <optional>
+#include <string>
+#include <vector>
+
+namespace {
+
+using OpenVFS::PlaceHolderAttributes;
+using OpenVFS::Registration;
+using OpenVFS::Constants::PinStates;
+using OpenVFS::Constants::States;
+using Rice::Data_Type;
+using Rice::Enum;
+using Rice::Module;
+
+std::filesystem::path path_from_string(const std::string &path)
+{
+    return std::filesystem::path(path);
+}
+
+std::string path_to_string(const std::filesystem::path &path)
+{
+    return path.string();
+}
+
+std::vector<uint8_t> bytes_from_string(const std::string &data)
+{
+    return {data.begin(), data.end()};
+}
+
+std::string string_from_bytes(const std::vector<uint8_t> &data)
+{
+    if (data.empty()) {
+        return {};
+    }
+    return {reinterpret_cast<const char *>(data.data()), data.size()};
+}
+
+}
+
+extern "C" void Init_openvfs()
+{
+    Module rb_mOpenVFS = Rice::define_module("OpenVFS");
+    Module rb_mConstants = Rice::define_module_under(rb_mOpenVFS, "Constants");
+
+    Enum<States> rb_eStates = Rice::define_enum_under<States>("States", rb_mConstants)
+        .define_value("Hydrated", States::Hydrated)
+        .define_value("DeHydrated", States::DeHydrated)
+        .define_value("Hydrating", States::Hydrating);
+
+    Enum<PinStates> rb_ePinStates = Rice::define_enum_under<PinStates>("PinStates", rb_mConstants)
+        .define_value("Unspecified", PinStates::Unspecified)
+        .define_value("OnlineOnly", PinStates::OnlineOnly)
+        .define_value("AlwaysLocal", PinStates::AlwaysLocal)
+        .define_value("Inherited", PinStates::Inherited)
+        .define_value("Excluded", PinStates::Excluded);
+
+    Module rb_mXAttributeNames = Rice::define_module_under(rb_mConstants, "XAttributeNames");
+    rb_mXAttributeNames.define_constant("Data", std::string(OpenVFS::Constants::XAttributeNames::Data));
+    rb_mXAttributeNames.define_constant("RealSize", std::string(OpenVFS::Constants::XAttributeNames::RealSize));
+    rb_mXAttributeNames.define_constant("Registration", std::string(OpenVFS::Constants::XAttributeNames::Registration));
+
+    Data_Type<Registration> rb_cRegistration = Rice::define_class_under<Registration>(rb_mOpenVFS, "Registration")
+        .define_singleton_function("register_filesystem", [](const std::string &path, const std::string &owner) {
+            return Registration::registerFilesystem(path_from_string(path), owner);
+        })
+        .define_singleton_function("from_attributes", [](const std::string &path) {
+            return Registration::fromAttributes(path_from_string(path));
+        })
+        .define_singleton_function("from_data", [](const std::string &path, const std::string &data) {
+            return Registration::fromData(path_from_string(path), bytes_from_string(data));
+        })
+        .define_singleton_function("unregister_filesystem", &Registration::unregisterFilesystem)
+        .define_method("to_data", [](const Registration &self) { return string_from_bytes(self.toData()); })
+        .define_method("path", [](const Registration &self) { return path_to_string(self.path()); })
+        .define_method("owner", &Registration::owner)
+        .define_method("version", &Registration::version)
+        .define_method("error", &Registration::error)
+        .define_method("ok?", &Registration::isOk);
+
+    Data_Type<PlaceHolderAttributes> rb_cPlaceHolderAttributes = Rice::define_class_under<PlaceHolderAttributes>(rb_mOpenVFS, "PlaceHolderAttributes")
+        .define_singleton_function("create", [](const std::string &path, const std::string &etag, const std::string &file_id, std::size_t size) {
+            return PlaceHolderAttributes::create(path_from_string(path), etag, file_id, size);
+        })
+        .define_singleton_function("from_data", [](const std::string &path, const std::string &data) {
+            return PlaceHolderAttributes::fromData(path_from_string(path), bytes_from_string(data));
+        })
+        .define_singleton_function("from_attributes", [](const std::string &path) {
+            return PlaceHolderAttributes::fromAttributes(path_from_string(path));
+        })
+        .define_method("to_data", [](const PlaceHolderAttributes &self) { return string_from_bytes(self.toData()); })
+        .define_method("real_size", &PlaceHolderAttributes::realSize)
+        .define_method("validate?", &PlaceHolderAttributes::validate)
+        .define_method("ok?", &PlaceHolderAttributes::isOk)
+        .define_method("absolute_path", [](const PlaceHolderAttributes &self) { return path_to_string(self.absolutePath); })
+        .define_method("absolute_path=", [](PlaceHolderAttributes &self, const std::string &path) { self.absolutePath = path_from_string(path); })
+        .define_attr("etag", &PlaceHolderAttributes::etag)
+        .define_attr("file_id", &PlaceHolderAttributes::fileId)
+        .define_attr("size", &PlaceHolderAttributes::size)
+        .define_attr("state", &PlaceHolderAttributes::state)
+        .define_attr("pin_state", &PlaceHolderAttributes::pinState);
+}

data/lib/openvfs/occ.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# Deliberately not "../openvfs": that pulls in the openvfs extension, which wraps the placeholder attributes libopenvfs keeps in extended attributes. Nothing here needs them, and upstream ships no Windows build of that library.
+require_relative "version"
+require "openvfs/occ/occ"
+
+require "fileutils"
+require "securerandom"
+
+module OpenVFS
+  # Writes the INI file AccountManager::restore and FolderMan::loadFolders read on start.
+  #
+  # The credential is not written here: credentials live in the keychain, so store it with Account#credential_manager.set("http/oauthtoken", credential) before starting.
+  #
+  # @parameter path [String] The local directory to sync.
+  # @parameter url [String] The server's base URL.
+  # @parameter remote_path [String] The WebDAV path to sync against.
+  # @parameter uuid [String] The account's UUID; also names the keychain entry.
+  # @parameter display_name [String] How the folder is named in logs.
+  # @parameter space_id [String] The space to sync, if any.
+  # @returns [String] The UUID the account was written under.
+  def self.configure(path, url:, remote_path:, uuid: SecureRandom.uuid, display_name: path, space_id: "")
+    config_path = File.join(Dir.home, ".config", "openvfs-rb", "openvfs-rb.cfg")
+    FileUtils.mkdir_p(File.dirname(config_path))
+    FileUtils.mkdir_p(path)
+
+    File.write(config_path, <<~CONFIG)
+      [Accounts]
+      1\\url=#{url}
+      1\\uuid=#{uuid}
+      size=1
+
+      [Folders]
+      1\\accountUUID=#{uuid}
+      1\\localPath=#{File.join(path, "")}
+      1\\journalPath=.sync_journal.db
+      1\\davUrl=#{remote_path}
+      1\\spaceId=#{space_id}
+      1\\displayString=#{display_name}
+      1\\paused=false
+      1\\ignoreHiddenFiles=true
+      1\\deployed=false
+      1\\priority=0
+      1\\virtualFilesMode=off
+      size=1
+    CONFIG
+
+    uuid
+  end
+end

data/lib/openvfs/rb/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Nathan Kidd.
+
+module OpenVFS
+  module Rb
+    VERSION = "1.0.0"
+  end
+end

data/lib/openvfs/rb.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Nathan Kidd.
+
+require_relative "rb/version"

data/lib/openvfs/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Nathan Kidd.
+
+require_relative "rb/version"
+
+module OpenVFS
+  VERSION = Rb::VERSION
+end

data/lib/openvfs-rb.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Nathan Kidd.
+
+require_relative "openvfs"

data/lib/openvfs.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Nathan Kidd.
+
+require_relative "openvfs/version"
+require "openvfs/openvfs"
+
+# A virtual filesystem.
+module OpenVFS
+end

data/license.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright, 2026, by Nathan Kidd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: openvfs-rb
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Nathan Kidd
+bindir: bin
+cert_chain: []
+date: 1980-01-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: gem_kit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: rice
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+email:
+- nathankidd@hey.com
+executables: []
+extensions:
+- ext/openvfs/extconf.rb
+- ext/openvfs/occ/extconf.rb
+extra_rdoc_files: []
+files:
+- README.md
+- ext/openvfs/extconf.rb
+- ext/openvfs/occ/extconf.rb
+- ext/openvfs/occ/sync.cpp
+- ext/openvfs/ruby_openvfs.cpp
+- lib/openvfs-rb.rb
+- lib/openvfs.rb
+- lib/openvfs/occ.rb
+- lib/openvfs/rb.rb
+- lib/openvfs/rb/version.rb
+- lib/openvfs/version.rb
+- license.md
+homepage: https://github.com/n-at-han-k/openvfs-rb
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/n-at-han-k/openvfs-rb
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: A virtual filesystem for Ruby.
+test_files: []