gleamrpc

Types

GleamRPCServerError

Errors that can occur of the server-side

pub type GleamRPCServerError(error) {
  WrongProcedure
  ProcedureExecError(error: ProcedureError)
  GetIdentityError(error)
  GetParamsError(errors: List(dynamic.DecodeError))
}

Constructors

```
WrongProcedure
```

ProcedureExecError(error: ProcedureError)

```
GetIdentityError(error)
```

GetParamsError(errors: List(dynamic.DecodeError))

Procedure

</>

A procedure is the equivalent of a function, but the execution of this function can be done remotely

pub type Procedure(params, return) {
  Procedure(
    name: String,
    router: option.Option(Router),
    type_: ProcedureType,
    params_type: convert.Converter(params),
    return_type: convert.Converter(return),
  )
}

Constructors

Procedure(
  name: String,
  router: option.Option(Router),
  type_: ProcedureType,
  params_type: convert.Converter(params),
  return_type: convert.Converter(return),
)

ProcedureCall

</>

A ProcedureCall combines a procedure and a procedure client.

pub type ProcedureCall(params, return, error) {
  ProcedureCall(
    procedure: Procedure(params, return),
    client: ProcedureClient(params, return, error),
  )
}

Constructors

ProcedureCall(
  procedure: Procedure(params, return),
  client: ProcedureClient(params, return, error),
)

A procedure client is a way to transmit the data of the procedure to execute and get back its data.
You should not create procedure clients directly, but rather use libraries such as gleamrpc_http_client.

pub type ProcedureClient(params, return, error) {
  ProcedureClient(
    call: fn(
      Procedure(params, return),
      params,
      fn(Result(return, GleamRPCError(error))) -> Nil,
    ) ->
      Nil,
  )
}

Constructors

ProcedureClient(
  call: fn(
    Procedure(params, return),
    params,
    fn(Result(return, GleamRPCError(error))) -> Nil,
  ) ->
    Nil,
)

ProcedureError

</>

An error that can occur during the execution of the implementation of a procedure

pub type ProcedureError {
  ProcedureError(message: String)
}

Constructors

```
ProcedureError(message: String)
```

ProcedureHandler

</>

A procedure handler is the heart of a procedure server.
It is a function that actually does the procedure detection, parameter decoding and implementation call.
You don’t have to worry about this type, it is managed by the gleamrpc package.

pub type ProcedureHandler(context, error) =
  fn(
    ProcedureIdentity,
    fn(ProcedureType, convert.GlitrType) ->
      Result(convert.GlitrValue, GleamRPCServerError(error)),
    context,
  ) ->
    Result(convert.GlitrValue, GleamRPCServerError(error))

ProcedureIdentity

</>

This is only useful for ProcedureServers

pub type ProcedureIdentity {
  ProcedureIdentity(
    name: String,
    router: option.Option(Router),
    type_: ProcedureType,
  )
}

Constructors

ProcedureIdentity(
  name: String,
  router: option.Option(Router),
  type_: ProcedureType,
)

ProcedureServer

</>

A procedure server is a way to receive data and map it to the correct procedure implementation.
It also handles parameter decoding, result encoding and error handling You should not create procedure servers directly, but rather use libraries such as gleamrpc_http_server.

pub type ProcedureServer(transport_in, transport_out, error) {
  ProcedureServer(
    get_identity: fn(transport_in) ->
      Result(ProcedureIdentity, GleamRPCServerError(error)),
    get_params: fn(transport_in) ->
      fn(ProcedureType, convert.GlitrType) ->
        Result(convert.GlitrValue, GleamRPCServerError(error)),
    recover_error: fn(GleamRPCServerError(error)) ->
      transport_out,
    encode_result: fn(convert.GlitrValue) -> transport_out,
  )
}

Constructors

ProcedureServer(
  get_identity: fn(transport_in) ->
    Result(ProcedureIdentity, GleamRPCServerError(error)),
  get_params: fn(transport_in) ->
    fn(ProcedureType, convert.GlitrType) ->
      Result(convert.GlitrValue, GleamRPCServerError(error)),
  recover_error: fn(GleamRPCServerError(error)) -> transport_out,
  encode_result: fn(convert.GlitrValue) -> transport_out,
)

ProcedureServerInstance

</>

A ProcedureServerInstance combines a procedure server and handler.
It also manages context creation and procedure registration.

pub type ProcedureServerInstance(
  transport_in,
  transport_out,
  context,
  error,
) {
  ProcedureServerInstance(
    server: ProcedureServer(transport_in, transport_out, error),
    handler: ProcedureHandler(context, error),
    context_factory: fn(transport_in) -> context,
    middlewares: List(
      ProcedureServerMiddleware(transport_in, transport_out),
    ),
  )
}

Constructors

ProcedureServerInstance(
  server: ProcedureServer(transport_in, transport_out, error),
  handler: ProcedureHandler(context, error),
  context_factory: fn(transport_in) -> context,
  middlewares: List(
    ProcedureServerMiddleware(transport_in, transport_out),
  ),
)

ProcedureServerMiddleware

</>

pub type ProcedureServerMiddleware(transport_in, transport_out) =
  fn(transport_in, fn(transport_in) -> transport_out) ->
    transport_out

ProcedureType

</>

pub type ProcedureType {
  Query
  Mutation
}

Constructors

```
Query
```
A query is a procedure that does not alter data, only retrieves it
```
Mutation
```
A mutation is a procedure that alters data (think create, update, delete)

Router

</>

Routers are a way to organize procedures

pub type Router {
  Router(name: String, parent: option.Option(Router))
}

Constructors

Router(name: String, parent: option.Option(Router))

Functions

call

</>

pub fn call(
  procedure_call: ProcedureCall(a, b, c),
  params: a,
  callback: fn(Result(b, GleamRPCError(c))) -> Nil,
) -> Nil

Execute the procedure call with the provided parameters. It should be used with the ‘use’ syntax.

Example:

use data <- gleamrpc.call(my_procedure |> gleamrpc.with_client(my_client()), my_params)

// do something with data

mutation

</>

pub fn mutation(
  name: String,
  router: Option(Router),
) -> Procedure(Nil, Nil)

Create a Mutation procedure

params

</>

pub fn params(
  procedure: Procedure(a, b),
  params_converter: Converter(c),
) -> Procedure(c, b)

Set the parameter type of the provided procedure

query

</>

pub fn query(
  name: String,
  router: Option(Router),
) -> Procedure(Nil, Nil)

Create a Query procedure

returns

</>

pub fn returns(
  procedure: Procedure(a, b),
  return_converter: Converter(c),
) -> Procedure(a, c)

Set the return type of the provided procedure

serve

</>

pub fn serve(
  server: ProcedureServerInstance(a, b, c, d),
) -> fn(a) -> b

Convert a server instance to a simple function

Example :

gleamrpc.with_server(http_server())
|> gleamrpc.with_implementation(my_procedure, implementation)
|> gleamrpc.serve
|> mist.new
|> mist.start_http

with_client

</>

pub fn with_client(
  procedure: Procedure(a, b),
  client: ProcedureClient(a, b, c),
) -> ProcedureCall(a, b, c)

Specify the client to use to call the provided procedure

with_context

</>

pub fn with_context(
  server: ProcedureServerInstance(a, b, c, d),
  context_factory: fn(a) -> e,
) -> ProcedureServerInstance(a, b, e, d)

Set the procedure server instance’s context factory function
It also unregisters all previously registered implementations, so it is better to call it first

with_implementation

</>

pub fn with_implementation(
  server: ProcedureServerInstance(a, b, c, d),
  procedure: Procedure(e, f),
  implementation: fn(e, c) -> Result(f, ProcedureError),
) -> ProcedureServerInstance(a, b, c, d)

with_middleware

</>

pub fn with_middleware(
  server: ProcedureServerInstance(a, b, c, d),
  middleware: fn(a, fn(a) -> b) -> b,
) -> ProcedureServerInstance(a, b, c, d)

Adds a middleware to be executed before/after executing the implementations.
Can be used to transform input or output data or to conditionally short-circuit execution.

with_server

</>

pub fn with_server(
  server: ProcedureServer(a, b, c),
) -> ProcedureServerInstance(a, b, a, c)

Create a procedure server instance for a server