Skip to content
DocumentationBuild a typed service
On this page

Page resources

Open Markdownllms.txtView source

Last updated

Build a typed service

This recipe follows ParcelHub's checked order lookup contract, native One implementation, generated Rust SDK, and ordinary lifecycle. The semantic and native One excerpts mirror the current owning example; shortened request and command forms remain illustrative end-product syntax.

1. Enter through one project

one.one establishes scope and selects the application source and exact lock:

one 1

semantic parcelhub.one
    domain one.project@1
    project ParcelHub@1
        source ./one/contracts.one
        source ./one/application.one
        source ./one/system.one
        source ./one/orders_get.one
        source ./one/orders_place.one
        source ./one/orders_cancel.one
        lock ./one.lock

The entry point contains no operation or implementation body.

2. Declare the operation

The semantic source owns nominal values, results, faults, effects, and the service boundary without choosing HTTP, a process, or a database:

one 1

semantic parcelhub.orders
    domain one.contracts@1
    schema CustomerId@1 = Identifier
    schema OrderId@1 = Identifier

    struct OrderKey@1
        customer_id: CustomerId
        order_id: OrderId

    enum OrderStatus@1
        pending
        canceled

    struct OrderView@1
        customer_id: CustomerId
        order_id: OrderId
        status: OrderStatus

    fault OrdersGetFault@1
        not found

    operation Orders.Get@1
        accepts OrderKey
        returns OrderView
        faults OrdersGetFault
        effect read
        deadline 1s
        invocation direct
        requires one.data.state#Read@1( resource: parcelhub.orders scope: fields(customer_id, order_id) )
        requires one.authority#ScopedStateRead@1( resource: parcelhub.orders scope: fields(customer_id, order_id) )

    service Orders@1
        expose Orders.Get

not_found is a domain outcome. Denial, cancellation, timeout, provider failure, and outcome unknown remain distinct outer dispositions.

3. Implement the exact claim

The implementation header claims one semantic target and one language profile. Checking and conformance still decide whether the claim is eligible:

impl parcelhub.implementation#OrdersGetOne@1
    realizes parcelhub.orders#Orders.Get@1
    using one.language.one#SafeAsync@1
    source
        use claim.requirements::state

        async Get(request: OrderKey) -> Result<OrderView, OrdersGetDomainFault> {
            match state::read(request, state) {
                some(stored) => ok(OrderView {
                    customer_id: request.customer_id,
                    order_id: request.order_id,
                    status: stored.status
                }),
                none => err(not_found)
            }
        }

The implementation receives only declared capabilities. It does not discover a database, network, secret, clock, or provider from the environment.

4. Check, test, and invoke

cargo test -p parcelhub --all-targets
cargo check -p parcelhub --no-default-features
one check --workspace systems/system-idl/examples/parcelhub --offline
{
  "customer_id": "7",
  "order_id": "42"
}

The invocation result preserves the exact operation revision, implementation claim, binding, principal, deadline, semantic result or fault, outer failure, and evidence references.

5. Add a protocol only at the edge

An HTTP projection can map Get to GET /orders/{order_id}, but the route is not the operation identity. A process-local caller can use the same operation without HTTP, and changing protocol does not revise the service meaning.

Executable evidence

The checked-in ParcelHub project owns the exact source, lock, generated SDK receipt, native One Get/Place/Cancel implementations, Rust contract tests, reactive-query test, and Developer Interface lifecycle evidence used by this recipe.

Next: add governed persistent state or ship the root.