Type-safe binary encoding and zero-copy memory operations for the Fidelity Framework.
🚧 Under Active Development 🚧
This project is in early development and not intended for production use.
BAREWire implements the BARE (Binary Application Record Encoding) protocol with F#'s type system providing compile-time safety. It enables zero-copy operations, structured memory access, and efficient inter-process communication - all without runtime overhead.
- Zero Dependencies: Pure F# implementation (FSharp.UMX for phantom types)
- Type Safety: Leverages units of measure for compile-time memory safety
- Zero-Copy Operations: Direct memory access without intermediate allocations
- Schema-Driven: Type-safe DSL for defining binary data structures
- Modular Design: Use only the components you need
BAREWire is part of the Fidelity native F# compilation ecosystem:
| Project | Role |
|---|---|
| Firefly | AOT compiler: F# → PSG → MLIR → Native binary |
| FNCS | F# Native Compiler Services (intrinsics, native types) |
| BAREWire | Binary encoding, memory mapping, zero-copy IPC |
| Farscape | C/C++ header parsing for native library bindings |
| XParsec | Parser combinators powering PSG traversal and header parsing |
The name "Fidelity" reflects the framework's core mission: preserving type and memory safety from source code through compilation to native execution.
BAREWire supports two compilation targets:
| Target | Use Case | Available Modules |
|---|---|---|
| Firefly | Native desktop/embedded applications | All modules |
| Fable | WREN stack WebSocket IPC | Encoding modules only |
The WREN Stack (WebView + Reactive + Embedded + Native) uses BAREWire for type-safe communication between the native Firefly backend and the Fable/JavaScript frontend:
┌─────────────────────────────────────────────────────────┐
│ WREN Stack Application │
├────────────────────┬────────────────────────────────────┤
│ Frontend (Fable) │ Backend (Firefly) │
│ Partas.Solid UI │ Native Application Logic │
├────────────────────┴────────────────────────────────────┤
│ WebSocket + BAREWire Binary Protocol │
└─────────────────────────────────────────────────────────┘
Dual-Target (Firefly + Fable):
BAREWire.Core.Buffer- Sequential write bufferBAREWire.Core.Binary- Byte conversion utilitiesBAREWire.Encoding.*- BARE encoding/decoding
Firefly-Only:
BAREWire.Core.Memory<'T,'region>- Capability-based memoryBAREWire.Memory.*- Region, View, SafeMemoryBAREWire.Core.Capability- Lifetime markers
BAREWire provides four interconnected capabilities:
Define binary data structures with a type-safe DSL:
open BAREWire.Schema.DSL
let messageSchema =
schema "Message"
|> withType "UserId" string
|> withType "Timestamp" int64
|> withType "Content" string
|> withType "Message" (struct' [
field "sender" (userType "UserId")
field "timestamp" (userType "Timestamp")
field "content" (userType "Content")
])
|> validate
|> Result.getConvert between F# values and compact binary representations:
open BAREWire.Encoding.Codec
type Message = {
Sender: string
Timestamp: int64
Content: string
}
// Encode to bytes
let encoded = encode messageSchema message buffer
// Decode from bytes
let decoded = decode<Message> messageSchema memoryAccess structured data in memory without copying:
open BAREWire.Memory.Region
open BAREWire.Memory.View
// Create a typed memory region
let region = create<Message, heap> data
// Create a view for field access
let view = View.create<Message, heap> region messageSchema
// Read fields directly from memory
let sender = View.getField<Message, string, heap> view ["sender"]Share typed data between processes:
open BAREWire.IPC.SharedMemory
// Process 1: Create shared region
let shared = create<Message> "channel" size messageSchema
// Process 2: Open existing region
let received = open'<Message> "channel" messageSchemaBAREWire uses F#'s units of measure and FSharp.UMX phantom types to prevent memory errors at compile time:
open FSharp.UMX
open BAREWire.Core
// Memory regions are typed
[<Measure>] type heap
[<Measure>] type stack
[<Measure>] type shared
// Offsets and sizes are dimensioned
let offset = 16<offset>
let size = 1024<bytes>
// Type system prevents mixing incompatible memory
let heapMem: Memory<Message, heap> = ...
let stackMem: Memory<Message, stack> = ...
// Cannot accidentally mix these - compile error!For embedded targets, BAREWire provides Peripheral Descriptors that capture memory-mapped hardware layouts:
type PeripheralDescriptor = {
Name: string // "GPIO"
Instances: Map<string, unativeint> // GPIOA → 0x48000000
Layout: PeripheralLayout
MemoryRegion: MemoryRegionKind // Peripheral | SRAM | Flash
}
type FieldDescriptor = {
Name: string // "ODR", "BSRR"
Offset: int // Byte offset from base
Type: RegisterType
Access: AccessKind // ReadOnly | WriteOnly | ReadWrite
}Farscape generates these descriptors from C/C++ headers (like CMSIS HAL), and Firefly's Alex component uses them to emit correct memory-mapped access code with proper volatile semantics.
BAREWire includes tools for evolving schemas safely:
open BAREWire.Schema.Analysis
match checkCompatibility oldSchema newSchema with
| FullyCompatible ->
printfn "Schemas are fully compatible"
| BackwardCompatible ->
printfn "New schema can read old data"
| ForwardCompatible ->
printfn "Old schema can read new data"
| Incompatible reasons ->
printfn "Breaking changes: %A" reasonssrc/
├── Core/ # Fundamental types and operations
│ ├── Binary.fs # Binary conversion (Dual-target ✓)
│ ├── Memory.fs # Buffer (Dual-target ✓) + Memory<'T,'region> (Firefly)
│ ├── Types.fs # Core type definitions and measures
│ ├── Utf8.fs # UTF-8 encoding/decoding (Dual-target ✓)
│ └── Capability.fs # Lifetime markers (Firefly only)
├── Encoding/ # BARE protocol implementation (Dual-target ✓)
│ ├── Codec.fs # Combined encode/decode
│ ├── Decoder.fs # Decoding primitives
│ └── Encoder.fs # Encoding primitives
├── Memory/ # Memory mapping and views (Firefly only)
│ ├── Region.fs # Memory region operations
│ ├── View.fs # Typed field access
│ └── Mapping.fs # Memory mapping functions
├── IPC/ # Inter-process communication (Firefly only)
│ ├── SharedMemory.fs # Shared memory regions
│ ├── MessageQueue.fs # Message queues
│ └── NamedPipe.fs # Named pipes
├── Network/ # Network protocol support
│ ├── Protocol.fs # Message passing primitives
│ ├── Transport.fs # Transport abstractions
│ └── Frame.fs # Wire frame format
└── Schema/ # Schema definition and validation
├── DSL.fs # Schema definition language
├── Definition.fs # Schema type definitions
├── Validation.fs # Schema validation
└── Analysis.fs # Compatibility checking
Legend: Modules marked "(Dual-target ✓)" work on both Firefly and Fable. All others are Firefly-only.
BAREWire is designed for high-performance scenarios:
- Zero-copy: Read structured data directly from memory/network buffers
- No allocations: Encoding/decoding can work with pre-allocated buffers
- Compact format: BARE encoding is smaller than JSON, MessagePack, or Protobuf
- Type-safe without overhead: All safety checks happen at compile time
For .NET projects:
dotnet add package BAREWireFor Fidelity/Firefly projects, BAREWire is included as source files via the project configuration.
BAREWire is under active development. Current focus:
- Core encoding/decoding for primitive and composite types
- Memory region abstractions
- Shared memory IPC
- Peripheral descriptor support for embedded targets
BAREWire is dual-licensed under both the Apache License 2.0 and a Commercial License.
For open source projects, academic use, non-commercial applications, and internal tools, use BAREWire under the Apache License 2.0.
A Commercial License is required for incorporating BAREWire into commercial products or services. See Commercial.md for details.
BAREWire includes technology covered by U.S. Patent Application No. 63/786,247 "System and Method for Zero-Copy Inter-Process Communication Using BARE Protocol". See PATENTS.md for licensing details.
Contributions are welcome! By submitting a pull request, you agree to license your contributions under the same dual license terms.
- BARE Protocol: The binary encoding specification
- FSharp.UMX: Phantom types for units of measure
- Firefly Team: For the native compilation infrastructure