export mod capability;

//! Domain-relative capability tables. Callers serialize shared table mutations.

use super::abi;

use super::limits;

use super::slots;

/// Authority stored in one live capability slot.

export record Entry: Copy {

    /// Authoritative kernel object kind.

    kind: abi::Kind,

    /// Generation-bearing reference in the table for this object kind.

    object: abi::Ref,

    /// Rights granted by this entry.

    rights: abi::Rights,

}

/// Fixed capability storage for one domain. Object records own their lifetimes.

export record Table: Copy {

    /// Domain whose calls select this table.

    owner: abi::Ref,

    /// Capability-slot generations and publication states.

    slots: [slots::Slot; limits::HANDLES],

    /// Payloads for live slots. Other payloads must not be read.

    entries: [Entry; limits::HANDLES],

}

/// Initialize a fresh table for a valid domain reference.

export fn initialize(table: &mut Table, owner: abi::Ref) {

    assert owner.index < limits::DOMAINS and owner.generation <> 0;

    set table.owner = owner;

    slots::initialize(&mut table.slots[..]);

}

/// Install authority after its object reference and lifetime have been acquired.

/// Invalid metadata or exhausted capacity leaves the table unchanged.

export fn install(table: &mut Table, entry: Entry) -> abi::Handle throws (abi::Error) {

    if entry.kind == abi::Kind::Empty or entry.object.generation == 0 {

        throw abi::Error::InvalidArg;

    }

    let rights = try abi::rights(*entry.rights as u64);

    let reservation = try slots::reserve(&mut table.slots[..]);

    let object = slots::reference(&reservation);

    set table.entries[object.index] = entry;

    let live = try! slots::commit(&mut table.slots[..], reservation);

    return try! abi::handle(entry.kind, live);

}

/// Read authoritative metadata after checking all encoded handle fields.

/// The caller validates the returned object reference against its object table.

export fn get(table: &Table, handle: abi::Handle) -> Entry throws (abi::Error) {

    let decoded = try abi::decode(handle);

    if not slots::matches(&table.slots[..], decoded.object, slots::State::Live) {

        throw abi::Error::BadHandle;

    }

    let entry = table.entries[decoded.object.index];

    if entry.kind <> decoded.kind {

        throw abi::Error::BadHandle;

    }

    return entry;

}

/// Require a live capability of the requested kind with all requested rights.

export fn lookup(table: &Table, handle: abi::Handle, kind: abi::Kind, rights: abi::Rights) -> Entry throws (abi::Error) {

    let entry = try get(table, handle);

    if entry.kind <> kind {

        throw abi::Error::BadHandle;

    }

    if not abi::permits(entry.rights, rights) {

        throw abi::Error::Denied;

    }

    return entry;

}

/// Obtain the current typed handle at a caller-relative slot index.

export fn at(table: &Table, index: u32, kind: abi::Kind) -> abi::Handle throws (abi::Error) {

    if index >= limits::HANDLES or table.slots[index].state <> slots::State::Live {

        throw abi::Error::BadHandle;

    }

    if table.entries[index].kind <> kind {

        throw abi::Error::BadHandle;

    }

    return try! abi::handle(kind, abi::Ref { index, generation: table.slots[index].generation });

}

/// Invalidate a handle and return the payload for object-specific release.

/// The caller completes payload teardown in the same serialized transaction.

export fn invalidate(table: &mut Table, handle: abi::Handle) -> Entry throws (abi::Error) {

    let entry = try get(table, handle);

    let decoded = try! abi::decode(handle);

    try slots::release(&mut table.slots[..], decoded.object);

    return entry;

}

/// Resolve resource authority. Zero selects the first live self-Domain entry

/// with all requested rights. Nonzero handles use ordinary Domain lookup.

export fn authority(table: &Table, handle: abi::Handle, rights: abi::Rights) -> Entry throws (abi::Error) {

    if *handle <> 0 {

        return try lookup(table, handle, abi::Kind::Domain, rights);

    }

    for i in 0..limits::HANDLES {

        if table.slots[i].state <> slots::State::Live {

            continue;

        }

        let entry = table.entries[i];

        if entry.kind == abi::Kind::Domain and entry.object == table.owner and abi::permits(entry.rights, rights) {

            return entry;

        }

    }

    throw abi::Error::Denied;

}

export mod capability;

//! Capability-table authority, generations, and domain-relative names.

use std::testing;

use kernel::abi;

use kernel::slots;

use kernel::limits;

use kernel::capability;

/// Construct one live object's capability metadata.

fn entry(kind: abi::Kind, index: u32, rights: u16) -> capability::Entry {

    return capability::Entry { kind, object: abi::Ref { index, generation: 1 }, rights: abi::Rights(rights) };

}

/// Check a rejected lookup's exact error without accepting successful lookup.

fn rejected(table: &capability::Table, value: abi::Handle, kind: abi::Kind, rights: u16, error: abi::Error)

    throws (testing::TestError)

{

    let mut failed = false;

    try capability::lookup(table, value, kind, abi::Rights(rights)) catch err {

        try testing::expect(err == error); set failed = true;

    };

    try testing::expect(failed);

}

/// Authoritative metadata controls kind, rights, and object identity.

@test unsafe fn lookup() throws (testing::TestError) {

    let mut table: capability::Table = undefined;

    capability::initialize(&mut table, abi::Ref { index: 0, generation: 1 });

    let page = entry(abi::Kind::Page, 9, abi::READ | abi::GRANT);

    let value = try! capability::install(&mut table, page);

    let found = try! capability::lookup(&table, value, abi::Kind::Page, abi::Rights(abi::READ));

    try testing::expect(found == page);

    let decoded = try! abi::decode(value);

    try testing::expect(try! capability::at(&table, decoded.object.index, abi::Kind::Page) == value);

    try rejected(&table, value, abi::Kind::Device, 0, abi::Error::BadHandle);

    try rejected(&table, value, abi::Kind::Page, abi::WRITE, abi::Error::Denied);

    let forged = try! abi::handle(abi::Kind::Device, decoded.object);

    try rejected(&table, forged, abi::Kind::Device, 0, abi::Error::BadHandle);

    try rejected(&table, abi::Handle(*value | 0x01000000), abi::Kind::Page, 0, abi::Error::BadHandle);

    try rejected(&table, abi::Handle(0), abi::Kind::Domain, 0, abi::Error::BadHandle);

    let outside = try! abi::handle(abi::Kind::Page, abi::Ref { index: limits::HANDLES, generation: 1 });

    try rejected(&table, outside, abi::Kind::Page, 0, abi::Error::BadHandle);

    let removed = try! capability::invalidate(&mut table, value);

    try testing::expect(removed == page);

    try rejected(&table, value, abi::Kind::Page, 0, abi::Error::BadHandle);

    let next = try! capability::install(&mut table, page);

    try testing::expect(next <> value);

    try rejected(&table, value, abi::Kind::Page, 0, abi::Error::BadHandle);

}

/// A copied number selects only authority already present in the receiver's table.

@test unsafe fn domainScope() throws (testing::TestError) {

    let mut left: capability::Table = undefined;

    let mut right: capability::Table = undefined;

    capability::initialize(&mut left, abi::Ref { index: 0, generation: 1 });

    capability::initialize(&mut right, abi::Ref { index: 1, generation: 1 });

    let value = try! capability::install(&mut left, entry(abi::Kind::Page, 7, abi::READ));

    try rejected(&right, value, abi::Kind::Page, 0, abi::Error::BadHandle);

    let local = try! capability::install(&mut right, entry(abi::Kind::Page, 8, abi::WRITE));

    try testing::expect(value == local);

    try rejected(&right, value, abi::Kind::Page, abi::READ, abi::Error::Denied);

    let actual = try! capability::lookup(&right, value, abi::Kind::Page, abi::Rights(abi::WRITE));

    try testing::expect(actual.object.index == 8);

}

/// Capacity failures preserve installed entries, and exhausted generations retire.

@test unsafe fn capacity() throws (testing::TestError) {

    let mut table: capability::Table = undefined;

    capability::initialize(&mut table, abi::Ref { index: 0, generation: 1 });

    let mut values: [abi::Handle; limits::HANDLES] = undefined;

    for i in 0..limits::HANDLES {

        set values[i] = try! capability::install(&mut table, entry(abi::Kind::Page, i, abi::READ));

    }

    let mut failed = false;

    try capability::install(&mut table, entry(abi::Kind::Page, 999, abi::READ)) catch err {

        try testing::expect(err == abi::Error::Exhausted); set failed = true;

    };

    try testing::expect(failed);

    for i in 0..limits::HANDLES {

        let found = try! capability::get(&table, values[i]);

        try testing::expect(found.object.index == i);

    }

    let old = try! capability::invalidate(&mut table, values[0]);

    set table.slots[0].generation = 0xffffffff;

    let last = try! capability::install(&mut table, old);

    let discarded = try! capability::invalidate(&mut table, last);

    try testing::expect(table.slots[0].state == slots::State::Retired);

    let mut retired = false;

    try capability::install(&mut table, old) catch err {

        try testing::expect(err == abi::Error::Exhausted); set retired = true;

    };

    try testing::expect(retired);

}

/// Zero selects a live self capability; unrelated authority and stale slots do not count.

@test unsafe fn selfAuthority() throws (testing::TestError) {

    let mut table: capability::Table = undefined;

    capability::initialize(&mut table, abi::Ref { index: 4, generation: 1 });

    let other = try! capability::install(&mut table, entry(abi::Kind::Domain, 5, abi::CREATE | abi::ALLOCATE));

    let page = try! capability::install(&mut table, entry(abi::Kind::Page, 4, abi::ALLOCATE));

    let oldDomain = capability::Entry { kind: abi::Kind::Domain, object: abi::Ref { index: 4, generation: 2 },

        rights: abi::Rights(abi::ALLOCATE) };

    let staleOwner = try! capability::install(&mut table, oldDomain);

    let mut failed = false;

    try capability::authority(&table, abi::Handle(0), abi::Rights(abi::ALLOCATE)) catch err {

        try testing::expect(err == abi::Error::Denied); set failed = true;

    };

    try testing::expect(failed);

    let explicit = try! capability::authority(&table, other, abi::Rights(abi::CREATE));

    try testing::expect(explicit.object.index == 5);

    let own = try! capability::install(&mut table, entry(abi::Kind::Domain, 4, abi::CREATE | abi::ALLOCATE));

    let authorized = try! capability::authority(&table, abi::Handle(0), abi::Rights(abi::CREATE | abi::ALLOCATE));

    try testing::expect(authorized.object == table.owner);

    let dropped = try! capability::invalidate(&mut table, own);

    let mut lost = false;

    try capability::authority(&table, abi::Handle(0), abi::Rights(abi::CREATE)) catch err {

        try testing::expect(err == abi::Error::Denied); set lost = true;

    };

    try testing::expect(lost);

}

/// Invalid installation metadata does not consume a slot or advance its generation.

@test unsafe fn invalidMetadata() throws (testing::TestError) {

    let mut table: capability::Table = undefined;

    capability::initialize(&mut table, abi::Ref { index: 0, generation: 1 });

    let mut bad = entry(abi::Kind::Empty, 0, 0);

    let mut failures: u32 = 0;

    for test in 0..3 {

        if test == 1 {

            set bad = entry(abi::Kind::Page, 0, 512);

        }

        if test == 2 {

            set bad = entry(abi::Kind::Page, 0, abi::READ);

            set bad.object.generation = 0;

        }

        try capability::install(&mut table, bad) catch err {

            try testing::expect(err == abi::Error::InvalidArg); set failures += 1;

        };

    }

    try testing::expect(failures == 3);

    let value = try! capability::install(&mut table, entry(abi::Kind::Page, 0, abi::READ));

    let decoded = try! abi::decode(value);

    try testing::expect(decoded.object.index == 0 and decoded.object.generation == 1);

    let mut invalid = false;

    try capability::at(&table, 0, abi::Kind::Device) catch err {

        try testing::expect(err == abi::Error::BadHandle); set invalid = true;

    };

    try testing::expect(invalid);

    set table.slots[0].state = slots::State::Reserved;

    try rejected(&table, value, abi::Kind::Page, 0, abi::Error::BadHandle);

    let mut pending = false;

    try capability::at(&table, 0, abi::Kind::Page) catch err {

        try testing::expect(err == abi::Error::BadHandle); set pending = true;

    };

    try testing::expect(pending);

}

/// Each resource-authority decision uses the complete rights of one live entry.

@test unsafe fn separateSelfRights() throws (testing::TestError) {

    let mut table: capability::Table = undefined;

    capability::initialize(&mut table, abi::Ref { index: 0, generation: 1 });

    let create = try! capability::install(&mut table, entry(abi::Kind::Domain, 0, abi::CREATE));

    let allocate = try! capability::install(&mut table, entry(abi::Kind::Domain, 0, abi::ALLOCATE));

    let selected = try! capability::authority(&table, abi::Handle(0), abi::Rights(abi::CREATE));

    try testing::expect(*selected.rights == abi::CREATE);

    let mut denied = false;

    try capability::authority(&table, abi::Handle(0), abi::Rights(abi::CREATE | abi::ALLOCATE)) catch err {

        try testing::expect(err == abi::Error::Denied); set denied = true;

    };

    try testing::expect(denied);

    let mut missing = false;

    try capability::authority(&table, allocate, abi::Rights(abi::CREATE)) catch err {

        try testing::expect(err == abi::Error::Denied); set missing = true;

    };

    try testing::expect(missing);

}