LibreSocial · Documentation

App Kernel — OSGi bootstrap, configuration, logging, filesystem

The eight bundles that turn an Equinox framework into a LibreSocial peer before any social feature loads (Source/org.lifesocial.core.main, .core.utilities, .core.logger, .core.filelogger, .core.filesystem, .core.equinoxconsole, Source/com.common.utilities, Source/org.libresocial.launcher) plus the launch descriptors (cnf/*.bndrun, build-logic/, Dockerfile, compose.yaml). Related: plugin system, overlay and P2P framework, monitoring.

Purpose

The kernel is everything in the peer that is neither the overlay/storage stack (com.p2pframework.*) nor a feature plugin. It owns the process, the on-disk layout, persistent configuration, the log stream and the operator console, and publishes the services every other bundle assumes:

Current implementation (as of 2026)

Working tree at ce9b710a1 (2026-11-12, master). Counts from the current tree.

Directory (Source/…) Bundle-SymbolicName .java lines @Component
org.lifesocial.core.main org.lifesocial.core 145 10 034 2
com.common.utilities com.common.utilities 14 1 963 0
org.lifesocial.core.utilities org.lifesocial.utilities 4 439 0
org.lifesocial.core.logger org.lifesocial.logger.component 4 382 1
org.lifesocial.core.filelogger org.lifesocial.filelogger.component 2 231 1
org.lifesocial.core.filesystem org.lifesocial.system.component 3 280 1
org.lifesocial.core.equinoxconsole org.lifesocial.equinoxconsole 1 135 1
org.libresocial.launcher org.libresocial.launcher 2 96 1

Directory names and symbolic names drift apart (org.lifesocial.core.logger → org.lifesocial.logger.component) and the bndrun files select bundles by osgi.identity, so those names are load-bearing; 128 of the 145 files in core.main are the exported data model, three are the kernel itself.

Bootstrap chain

./gradlew runOsgi drives org.libresocial.buildtool.osgi-runtime in build-logic: DetectPlatformTask writes build-conf/platform-description.json (OS sanitised to win32|macosx|linux, arch to x86_64|x86|aarch64), the matching cnf/org.libresocial.launcher.${os}.${arch}.bndrun is selected — each one -include:s org.libresocial.launcher.common.bndrun and adds only the platform SWT fragment plus runblacklist entries for foreign-OS fragments — then syncRuntimeRepo publishes every subproject jar into cnf/runtime-repo (index.xml, registered as OSGiRepository in cnf/build.bnd) and bnd 7.2.3 resolves with -resolve: beforelaunch and starts Equinox (-runfw: org.eclipse.osgi):

Inside the framework, ApplicationRunnable (@Component(service = Runnable.class, property = "main.thread=true")) instantiates org.lifesocial.ui.Application, an Eclipse IApplication, and calls start(new SimpleApplicationContext()). That context is the minimal contract the SWT shell needs: empty APPLICATION_ARGS, branding ids legacy.app/legacy-app, application id org.lifesocial.ui.application; the launcher prints LibreSocial Launcher 1.0.0 and nothing else. The legacy path still exists in parallel: org.lifesocial.ui/config/plugin.xml declares the org.eclipse.core.runtime.applications extension and the product org.lifesocial.ui.product that eclipse.product selects. main.thread=true is metadata only — the string exists in Equinox's EclipseAppDescriptor (main.thread/any.thread) and no class here reads it.

Container path

prepareContainerContext syncs cnf/*.bndrun, cnf/build.bnd and the runtime-repo jars into build/container-context/ and renames biz.aQute.bnd-*.jar to bnd/bnd.jar. The image (eclipse-temurin:21-jdk-jammy, libgtk-3-0, non-root libresocial user) runs java -jar /opt/libresocial/bnd/bnd.jar run cnf/org.libresocial.launcher.linux.x86_64.bndrun, so the resolver runs inside the container at start-up. compose.yaml publishes 8443 (web UI), 10001 (console, host-bound to 127.0.0.1) and 9001 (Pastry). Since osgi.console=localhost:10001 would be unreachable from outside the container, CI rewrites the bind host in the staged copy (sed -i 's/^\([[:space:]]*osgi\.console=\)localhost:/\10.0.0.0:/', 00536649e, corrected in a94feb903). The console default became 10001 — network port + 1000 — in 0967596b8; the tree's last commit (ce9b710a1) only updates that value in .env. The data volume is commented out ("Enable volume after fixing the storage backend"), so container state is ephemeral.

Application object

LifeSocial is @Component(name = "LifeSocial", immediate = true, service = ILifeSocial.class) and implements ISaveConfigurationListener. activate() builds a LifeSocialConfiguration, reads PropertiesContainer.CONFIG_FILE when it exists, mkdirs the working directory and P2PFramework, then setupFramework(): setDebugMode(false), setApplicationDirectory(P2PFramework), ringDispatcher.setCurrentRing(...), setRingManagerUpdateIntervall(...). The framework arrives as a DS reference — @Reference(name = "Framework", policy = DYNAMIC, unbind = "unsetFramework") on a setFramework(Framework) setter that also registers the component as a save listener; core.main reaches com.p2pframework via Require-Bundle, never the other way round. deactivate() and any framework-driven save() call saveConfiguration(): read the framework back into the configuration objects, ringDispatcher.storeSettingsNow(), config.writeToFile(CONFIG_FILE).

The bundle also exports the platform's shared vocabulary: data.interfaces (Storable, Payload, Header, StorageKey), the per-feature DTO packages, events (EventManagerCore, EventConstCore), commands (ICommands, AbstractCommands, ICommandHandler) and commoninterfaces (Plugin, Observer).

Open defect. LifeSocial.getFramework() (lines 91–92) is return this.getFramework(); — a self-recursive call ending in a StackOverflowError for its callers. Present since 88b9632df (2013-12-16) and still at HEAD; SystemComponent.activate() depends on exactly that chain (((LifeSocial) lifeSocial).getFramework().getConfiguration().getStorageDirectory(), with a TODO asking to put the storage directory on ILifeSocial instead). Reported as observed, not fixed by this survey.

Configuration layers

Layer Where Written at run time Read by
static tuning config/LibreSocialConfig.txt, bundle resource of org.lifesocial.utilities (99 lines) never ConfigLoader (getResourceAsStream, throws if absent) — messagedispatcher, SignStorageDispatcher, SocialCache, monitoring, tester
node state ~/.LibreSocial/config.conf (XML) LifeSocialConfiguration.writeToFile on save/shutdown readFromFile in activate()
launch properties -runproperties, -runprogramargs, -runvm operator / CI Equinox, Eclipse runtime, console

AbstractConfiguration enforces by reflection that each subclass declares static final String SECTION, and stores every value in a HierarchicalProperties under SECTION + key, so keys are path-qualified (/FrameworkConfig/CURRENT_RING, /ApplicationConfig/ChatPlugin/refreshTime) and a plugin adds a section by contributing a subclass. FrameworkConfiguration holds CURRENT_RING (UUID) and RING_MANAGER_UPDATE_INTERVALL (30 000 ms), with DEFAULT_NETWORK_LOCAL_PORT = 9001; a 2026 fix matters on first start, because set(key, null) into a ConcurrentHashMap crashed LifeSocial.activate().

The tuning file holds the platform's behavioural switches and is read verbatim today: storage (replicationFactor = 4, CanYouProvideTimeOut = 7000, objectSizeCalculationEnabled = 1, autoDeleteStorage = 0), capacity/heterogeneity (enableHeterogeneityAwareness = 1, heterogeneityCacheSize = 50), the social-cache block (socialCacheEnabled = 1, socialCacheUpdater = socialscore, socialCacheUpdateLimit = 2, socialCacheMUCLimit = 150), DSS tuning (dds_split_size = -1, dds_linkedlist_consolidation = true, justParallel = 0, parallelity = 1, combineParameter = 3), monitoring (autoStartMonitoring = 0, measuringData = 1, socialMetricCollection = 1, monitoringToGnuplot/SQLite/Dat/CSV = 0, mobileNodes = 0), routing (disablePIRouting = 1) and UX (autoFriendRequestAccept = 1, autoLiveChatInvitationAccept = 1, autoVotingInvitationAccept = 1). Booleans are 1/0, parsed as value == 1; monitoring is off by default since the 2026 stability pass.

PropertiesContainer supplies the constants: WorkingDir = PlatformIndependence.getApplicationDataDirectory("LibreSocial") → ~/.LibreSocial (Linux), ~/AppData/Local/LibreSocial (Windows), ~/Library/Application Support/LibreSocial (macOS); P2PFrameworkDir = WorkingDir/P2PFramework; CONFIG_FILE = WorkingDir/config.conf; timeouts (RequestTimeout and SystemValidityPeriod 10 s, LoginTimeout 120 s, StandardWaitingTime 30 × 1200 tries); negative status codes −100…−114 and −130…−135; plugin ids and tokens. The Linux location keeps being renegotiated: 17f4cda9f (2016-07-27, "changed path where storage is located on linux to avoid problem with nfs") moved it to $PWD/.LibreSocial; the 2026 refactor returned to $HOME.

Logging, filesystem, console

LogServiceComponent (@Component(name = "LOG", service = ILogService.class)) forwards info/warning/error/debug, with and without Class/Throwable, to the standard org.osgi.service.log.LogService (DYNAMIC reference) and keeps recent entries for getLogEntries(); observers attach through registerLoggingClient. That buffer is now a bounded ArrayDeque of MAX_LOG_ENTRIES = 5000, and the source comment records why: the unbounded ArrayList retained every line, so a component spamming failed lookups (SignStorageDispatcher "Item not found") piled up tens of millions of entries until the JVM died in a GC death spiral (d9ccc75b9, 2026-07-06).

FileLoggerComponent (@Component(name = "FileLogger")) implements LogListener, attaches to LogReaderService in activate(), and writes <WorkingDir>/log/Lifesocial - <yyyy_M_d (H.m.s)>.log, deleting a pre-existing file of the same name; isLogToScreen mirrors DEBUG, WARNING and ERROR to stderr but not INFO. SystemComponent (ISystem) implements cleanUp(), getStorageDirectory(), getDiskSpaceUsage(): it records the initial directory size, appends tracked directories to WorkingDir/LSTrack.trk, and reports usage as current minus initial; cleanUp() deletes them only if CleanUpLocalStorage is true, and it is false, so shutdown never discards node data. EquinoxConsole (service = CommandProvider.class, symbolic name with singleton:=true) contributes _execute, _showall, _helpls, _gethelpfor and getHelp(), delegating to the injected ICommandsComponent and forwarding TimeoutException; since ba7b37a10 (2026-11-11) the plugin-side command references are MULTIPLE/DYNAMIC and 14 bundles carry -dsannotations-options: inherit, so the console keeps working with a partially satisfied plugin set.

Build and packaging

All eight bundles are Gradle projects applying osgi-bundle-conventions.gradle: Java 17 Adoptium toolchain, sources in src, resources from resources and config, jar metadata from bnd reading a per-bundle bnd.bnd, -dsannotations: * where DS components exist. cnf/build.bnd pins -runee: JavaSE-17 and downgrades bnd's "classes found in the wrong directory" error to a warning. com.common.utilities is the only kernel bundle with DynamicImport-Package: *; org.lifesocial.core still uses Require-Bundle for org.lifesocial.utilities, org.lifesocial.logger.component, com.p2pframework, com.common.utilities and rice.freepastry — the Import-Package lesson from 2008 never applied here. SWT 3.128 is wrapped as bundles under bundle-wrapper/ (f523b23dc).

Design options and decision

The 2008 OSGi study states its options and decision explicitly; entries marked reconstructed are inferred from commits and comments.

Technical details

Declarative Services graph (kernel).

Component name Provided service References (all DYNAMIC with unbind)
LifeSocial (immediate) ILifeSocial Framework → com.p2pframework.Framework
LOG ILogService org.osgi.service.log.LogService
FileLogger LogListener logReader (LogReaderService), ILogService (bound, unused)
SystemComponent ISystem LOG (ILogService), LifeSocial (ILifeSocial)
equinoxconsole org.eclipse.osgi.framework.console.CommandProvider COMMANDS → ICommandsComponent
ApplicationRunnable Runnable (main.thread=true) none

All references being DYNAMIC is what lets bundles stop in any order, at the price of NullPointerExceptions when a component is used after unbinding. SystemComponent also carries a dead overload unsetLogService(ILifeSocial) that nulls the lifeSocial field — misleading, since that reference's unbind method is unsetLifeSocial.

Ports and start levels.

Port Owner Source
9001 Pastry bind/bootstrap FrameworkConfiguration.DEFAULT_NETWORK_LOCAL_PORT, mirrored by com.p2pframework.Configuration, which probes a free port with NetworkHelper.findAvailablePort
10001 Equinox console (telnet) -runproperties: osgi.console=localhost:10001; compose maps LIBRESOCIAL_CONSOLE_HOST_PORT
8443 web UI / REST WebProvider.PORT; the fallback loop walks the cause chain because Jetty 12 wraps BindException (e49c67c60)
8080 webprovider instance manager INSTANCEMANAGER_PORT

On-disk layout (Linux). ~/.LibreSocial/config.conf (node state, written on save/shutdown), ~/.LibreSocial/LSTrack.trk (directories tracked by SystemComponent), ~/.LibreSocial/log/Lifesocial - <yyyy_M_d (H.m.s)>.log, and ~/.LibreSocial/P2PFramework/ as the com.p2pframework application directory, holding log/ and storage/<ringId>/ for local PAST/Kryo data.

Shared helpers (com.common.utilities, 14 classes, zero DS components by design — a plain library usable from static initializers such as PropertiesContainer). PlatformIndependence (OS/arch detection, data directory); NetworkHelper (rewritten 2026: interface enumeration, loopback-safe IPv4 selection, findAvailablePort, BOOTSTRAP_ADDRESS resolving www.hhu.de) — the code where the multi-loopback failure Imam documented on Debian/Ubuntu had to be fixed, feeding com.p2pframework ring configuration and the STUN bundle; HierarchicalProperties/Node/XMLHelper (path keys, XML import/export — the backing store of config.conf); BlockingExecutor; FileUtils, ArrayHelper, ImageHelper, MathUtil, Soundex/WeightedLevenshteinDistance, Tree.

Evolution and supersession

Core architecture and the OSGi decision

Platform papers documenting the runtime

Monitoring switches carried by the kernel configuration

Configuration keys defined here, consumed further down

Revival, build and operation