main.zig

// SPDX-License-Identifier: MPL-2.0
// Copyright (c) 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
//
// TYPED_WASM FFI Implementation
//
// This module is the C-compatible Zig FFI surface. Types and result codes
// are hand-maintained in parallel with the Idris2 ABI spread across
// src/abi/{Region,TypedAccess,Pointer,Effects,Lifetime,Linear,
// MultiModule}.idr and src/abi/Layout/*.idr. There is no automated
// Idris2 -> C header pipeline yet; see docs/architecture/ABI-PIPELINE.adoc
// for the gap analysis and the plan for closing it.
//
// SPDX-License-Identifier: MPL-2.0

const std = @import("std");

// Version information (keep in sync with project)
const VERSION = "0.1.0";
const BUILD_INFO = "TYPED_WASM built with Zig " ++ @import("builtin").zig_version_string;

/// Thread-local error storage
threadlocal var last_error: ?[]const u8 = null;

/// Set the last error message
fn setError(msg: []const u8) void {
    last_error = msg;
}

/// Clear the last error
fn clearError() void {
    last_error = null;
}

//==============================================================================
// Core Types (must match src/abi/Types.idr)
//==============================================================================

/// Result codes (must match Idris2 Result type)
pub const Result = enum(c_int) {
    ok = 0,
    @"error" = 1,
    invalid_param = 2,
    out_of_memory = 3,
    null_pointer = 4,
};

/// Library handle: *truly* opaque to C — a pointer-only incomplete type
/// (FILE*-style). zig 0.15 forbids fields on `opaque`, which is correct: an
/// opaque type has no known size/alignment/layout, so it cannot carry fields.
/// The real state lives in `HandleImpl`, hidden behind the pointer; C only
/// ever holds a `*Handle` and never sees the implementation's size or fields.
/// This preserves the original "opaque to prevent direct access" intent
/// rather than downgrading to a plain struct.
pub const Handle = opaque {};

/// The concrete state behind a `*Handle`. Internal; never exposed across the
/// C ABI. Conjured/recovered via `impl()`.
const HandleImpl = struct {
    allocator: std.mem.Allocator,
    initialized: bool,
    // Add further fields here.
};

/// Recover the implementation struct from an opaque handle pointer.
inline fn impl(handle: *Handle) *HandleImpl {
    return @ptrCast(@alignCast(handle));
}

//==============================================================================
// Library Lifecycle
//==============================================================================

/// Initialize the library
/// Returns a handle, or null on failure
export fn typed_wasm_init() ?*Handle {
    const allocator = std.heap.c_allocator;

    const self = allocator.create(HandleImpl) catch {
        setError("Failed to allocate handle");
        return null;
    };

    // Initialize state
    self.* = .{
        .allocator = allocator,
        .initialized = true,
    };

    clearError();
    return @ptrCast(self);
}

/// Free the library handle
export fn typed_wasm_free(handle: ?*Handle) void {
    const h = impl(handle orelse return);
    const allocator = h.allocator;

    // Clean up resources
    h.initialized = false;

    allocator.destroy(h);
    clearError();
}

//==============================================================================
// Core Operations
//==============================================================================

/// Process data (example operation)
export fn typed_wasm_process(handle: ?*Handle, input: u32) Result {
    const h = impl(handle orelse {
        setError("Null handle");
        return .null_pointer;
    });

    if (!h.initialized) {
        setError("Handle not initialized");
        return .@"error";
    }

    // Example processing logic
    _ = input;

    clearError();
    return .ok;
}

//==============================================================================
// String Operations
//==============================================================================

/// Get a string result (example)
/// Caller must free the returned string
export fn typed_wasm_get_string(handle: ?*Handle) ?[*:0]const u8 {
    const h = impl(handle orelse {
        setError("Null handle");
        return null;
    });

    if (!h.initialized) {
        setError("Handle not initialized");
        return null;
    }

    // Example: allocate and return a string
    const result = h.allocator.dupeZ(u8, "Example result") catch {
        setError("Failed to allocate string");
        return null;
    };

    clearError();
    return result.ptr;
}

/// Free a string allocated by the library
export fn typed_wasm_free_string(str: ?[*:0]const u8) void {
    const s = str orelse return;
    const allocator = std.heap.c_allocator;

    const slice = std.mem.span(s);
    allocator.free(slice);
}

//==============================================================================
// Array/Buffer Operations
//==============================================================================

/// Process an array of data
export fn typed_wasm_process_array(
    handle: ?*Handle,
    buffer: ?[*]const u8,
    len: u32,
) Result {
    const h = impl(handle orelse {
        setError("Null handle");
        return .null_pointer;
    });

    const buf = buffer orelse {
        setError("Null buffer");
        return .null_pointer;
    };

    if (!h.initialized) {
        setError("Handle not initialized");
        return .@"error";
    }

    // Access the buffer
    const data = buf[0..len];
    _ = data;

    // Process data here

    clearError();
    return .ok;
}

//==============================================================================
// Error Handling
//==============================================================================

/// Get the last error message
/// Returns null if no error
export fn typed_wasm_last_error() ?[*:0]const u8 {
    const err = last_error orelse return null;

    // Return C string (static storage, no need to free)
    const allocator = std.heap.c_allocator;
    const c_str = allocator.dupeZ(u8, err) catch return null;
    return c_str.ptr;
}

//==============================================================================
// Version Information
//==============================================================================

/// Get the library version
export fn typed_wasm_version() [*:0]const u8 {
    return VERSION.ptr;
}

/// Get build information
export fn typed_wasm_build_info() [*:0]const u8 {
    return BUILD_INFO.ptr;
}

//==============================================================================
// Callback Support
//==============================================================================

/// Callback function type (C ABI). zig 0.15 renamed the calling-convention
/// tag `.C` to `.c` (CallingConvention became a union to carry per-CC params).
pub const Callback = *const fn (u64, u32) callconv(.c) u32;

/// Register a callback
export fn typed_wasm_register_callback(
    handle: ?*Handle,
    callback: ?Callback,
) Result {
    const h = impl(handle orelse {
        setError("Null handle");
        return .null_pointer;
    });

    const cb = callback orelse {
        setError("Null callback");
        return .null_pointer;
    };

    if (!h.initialized) {
        setError("Handle not initialized");
        return .@"error";
    }

    // Store callback for later use
    _ = cb;

    clearError();
    return .ok;
}

//==============================================================================
// Utility Functions
//==============================================================================

/// Check if handle is initialized
export fn typed_wasm_is_initialized(handle: ?*Handle) u32 {
    const h = impl(handle orelse return 0);
    return if (h.initialized) 1 else 0;
}

//==============================================================================
// Tests
//==============================================================================

test "lifecycle" {
    const handle = typed_wasm_init() orelse return error.InitFailed;
    defer typed_wasm_free(handle);

    try std.testing.expect(typed_wasm_is_initialized(handle) == 1);
}

test "error handling" {
    const result = typed_wasm_process(null, 0);
    try std.testing.expectEqual(Result.null_pointer, result);

    const err = typed_wasm_last_error();
    try std.testing.expect(err != null);
}

test "version" {
    const ver = typed_wasm_version();
    const ver_str = std.mem.span(ver);
    try std.testing.expectEqualStrings(VERSION, ver_str);
}