Packages

package rpc

Ordering
  1. Alphabetic
Visibility
  1. Public
  2. All

Type Members

  1. trait AsRaw[Raw, Real] extends AnyRef
    Annotations
    @implicitNotFound( ... )
  2. trait AsRawReal[Raw, Real] extends AsReal[Raw, Real] with AsRaw[Raw, Real]
    Annotations
    @implicitNotFound( ... )
  3. trait AsReal[Raw, Real] extends AnyRef
    Annotations
    @implicitNotFound( ... )
  4. final case class Fallback[+T](value: T) extends AnyVal with Product with Serializable

    Wrap your implicit instance of AsReal, AsRaw, AsRawReal or RPC metadata (with companion that extends RpcMetadataCompanion into Fallback in order to lower its implicit priority.

    Wrap your implicit instance of AsReal, AsRaw, AsRawReal or RPC metadata (with companion that extends RpcMetadataCompanion into Fallback in order to lower its implicit priority. Useful when some implicit must be imported but we don't want it to get higher priority that imports normally have over implicit scope (e.g. implicits from companion objects).

    NOTE: Fallback does not work for *all* typeclasses, only RPC-related ones (AsReal, AsRaw, etc). You can make it work with your own typeclass, but you must define appropriate forwarder in its companion, e.g.

    trait FallbackAwareTC[T] { ... }
    object FallbackAwareTC {
      implicit def fromFallback[T](implicit f: Fallback[FallbackAwareTC[T]]): FallbackAwareTC[T] = f.value
    }
  5. trait FunctionRPCFramework extends RPCFramework

    Mix in this trait into your RPC framework to support remote functions, i.e.

    Mix in this trait into your RPC framework to support remote functions, i.e. methods which asynchronously return some result (Future[A] where A has a Reader and Writer).

  6. trait GetterRPCFramework extends RPCFramework

    Mix in this trait into your RPC framework to support getters, i.e.

    Mix in this trait into your RPC framework to support getters, i.e. methods that return RPC subinterfaces

  7. trait MetadataAnnotation extends Annotation with StaticAnnotation

    Annotations that extend this trait will be retained for runtime in RPCMetadata typeclass instances

  8. trait OneWayRPCFramework extends GetterRPCFramework with ProcedureRPCFramework
  9. trait ProcedureRPCFramework extends RPCFramework

    Mix in this trait into your RPC framework to support remote procedures, i.e.

    Mix in this trait into your RPC framework to support remote procedures, i.e. fire-and-forget methods with Unit return type.

  10. trait RPCFramework extends AnyRef
  11. trait RawRpcCompanion[Raw] extends RpcImplicitsProvider

    Base trait for companion objects of raw RPC traits.

  12. sealed trait RpcEncoding extends Annotation with RawMethodAnnotation with RawParamAnnotation

    Base trait for verbatim and encoded.

    Base trait for verbatim and encoded. These annotations can be applied either on a raw method or raw parameter in order to specify how matching real method results or matching real parameter values are encoded as raw values. Currently there are two possible cases: verbatim (no encoding) and encoded (encoding using AsRaw and AsReal typeclasses). By default, method return values and multi parameters are encoded while single and optional parameters are verbatim. See documentation of verbatim and encoded for more details.

  13. class RpcException extends RuntimeException
  14. trait RpcImplicitsProvider extends AnyRef
  15. trait RpcMacroInstances[Implicits, InstancesTrait[_], Real] extends AnyRef

    Intermediate factory that creates an InstancesTrait for given Real RPC trait, based on provided Implicits.

    Intermediate factory that creates an InstancesTrait for given Real RPC trait, based on provided Implicits. Normally, this factory is used as implicit constructor parameter of base classes for companion objects of RPC traits (e.g. DefaultRestApiCompanion). This all serves to reduce boilerplate associated with RPC trait companion declarations and makes RPC trait definitions as concise as possible. It also lets the programmer easily inject additional implicits into macro-materialization of RPC-related typeclasses (AsReal, AsRaw, metadata, etc.).

    An InstancesTrait is a trait that aggregates multiple RPC related typeclass instances for given Real RPC trait. There is no fixed interface for InstancesTrait, its members are inspected by materialize macro and implemented automatically. InstancesTrait must contain only parameterless abstract methods that return either AsRaw[Raw,Real], AsReal[Raw,Real], AsRawReal[Raw,Real] or some RPC metadata class for Real. The Raw type is arbitrary and may be different for every method. However, it must be a concrete raw RPC trait so that it's further understood by the macro engine. All methods of the InstancesTrait are macro-implemented using AsRaw/AsReal/AsRawReal/RpcMetadata.materializeForRpc macros.

    Example of InstancesTrait: ClientInstances

    The Implicits type is typically a trait with a collection of implicit definitions whose companion object implements that trait, e.g. DefaultRestImplicits. When the macro implements apply method of RpcMacroInstances contents of Implicits are imported into the body of apply and visible further by macros that materialize InstancesTrait.

    If RpcMacroInstances is accepted as implicit super constructor parameter of a companion object (which is the typical situation) then this reference should be passed as companion. This is in order to work around https://github.com/scala/bug/issues/7666

  16. trait RpcMetadataCompanion[M[_]] extends MetadataCompanion[M] with RpcImplicitsProvider
  17. trait RpcTag extends Annotation with RealSymAnnotation

    Base trait for RPC tag annotations.

    Base trait for RPC tag annotations. Tagging gives more direct control over how real methods and their parameters are matched against raw methods and their parameters. For more information about method tagging, see documentation of methodTag. For more information about parameter tagging, see documentation of paramTag.

  18. trait StandardRPCFramework extends GetterRPCFramework with FunctionRPCFramework with ProcedureRPCFramework
  19. final class encoded extends Annotation with RpcEncoding

    When a raw parameter is annotated as encoded, macro generated code will translate between real parameter values and raw parameter values using implicit instances of AsRaw[Raw,Real] and AsReal[Raw,Real] typeclasses.

    When a raw parameter is annotated as encoded, macro generated code will translate between real parameter values and raw parameter values using implicit instances of AsRaw[Raw,Real] and AsReal[Raw,Real] typeclasses. This annotation may also be applied on a method, but this would be redundant since method results are encoded by default.

    Here's an example of raw RPC definition supposed to handle asynchronous (Future-based) calls that uses GenCodec in order to encode and decode arguments and results as JSON strings. It introduces its own wrapper class for JSON strings that has appropriate implicit instances of AsRaw and AsReal (or AsRawReal which serves as both AsReal and AsRaw).

    import com.avsystem.commons._
    import com.avsystem.commons.rpc._
    import com.avsystem.commons.serialization._
    import com.avsystem.commons.serialization.json._
    
    case class Json(jsonStr: String)
    object Json {
      private def readJson[T: GenCodec](json: Json): T =
        JsonStringInput.read[T](json.jsonStr)
    
      private def writeJson[T: GenCodec](value: T): Json =
        Json(JsonStringOutput.write[T](value))
    
      implicit def genCodecBasedJsonEncoding[T: GenCodec]: AsRawReal[T,Json] =
        AsRawReal.create[Json,T](writeJson[T], readJson[T])
    
      // instead of using `mapNow`, this method can also take implicit ExecutionContext and just use `map`
      implicit def genCodecBasedFutureJsonEncoding[T: GenCodec]: AsRawReal[Future[Json],Future[T]] =
        AsRawReal.create[Future[Json],Future[T]](_.mapNow(writeJson[T]), _.mapNow(readJson[T]))
    }
    
    trait AsyncRawRpc {
      def call(@methodName rpcName: String, @multi args: Map[String,Json]): Future[Json]
    }

    If you don't want to introduce the wrapper Json class and use more raw type, e.g. plain String then you can also do it by moving implicit instances of AsReal and AsRaw (or the joined AsRawReal) into the implicits object of raw RPC companion:

    trait AsyncRawRpc {
      def call(@methodName rpcName: String, @multi args: Map[String,String]): Future[String]
    }
    object AsyncRawRpc extends RawRpcCompanion[AsyncRawRpc] {
      private def readJson[T: GenCodec](json: String): T =
        JsonStringInput.read[T](json)
      private def writeJson[T: GenCodec](value: T): String =
        JsonStringOutput.write[T](value)
    
      override object implicits {
        implicit def genCodecBasedJsonEncoding[T: GenCodec]: AsRawReal[String,T] =
          AsRawReal.create[String,T](writeJson[T], readJson[T])
        implicit def genCodecBasedFutureJsonEncoding[T: GenCodec]: AsRawReal[Future[String],Future[T]] =
          AsRawReal.create[Future[String],Future[T]](_.mapNow(writeJson[T]), _.mapNow(readJson[T]))
      }
    }
  20. final class methodName extends Annotation with RawParamAnnotation

    May be applied on raw method parameter of type String to indicate that macro generated implementation of AsReal should pass real method's RPC name as this parameter and that macro generated implementation of AsRaw should expect real method's RPC name to be passed there.

    May be applied on raw method parameter of type String to indicate that macro generated implementation of AsReal should pass real method's RPC name as this parameter and that macro generated implementation of AsRaw should expect real method's RPC name to be passed there.

    Macro generation of AsRaw implementations require that raw methods annotated as multi must take at least one raw parameter annotated as methodName (it may also be aggregated into some composite parameter). This is necessary to properly identify which real method should be called.

  21. final class methodTag[BaseTag <: RpcTag] extends Annotation with RawSymAnnotation

    Method tagging lets you have more explicit control over which raw methods can match which real methods.

    Method tagging lets you have more explicit control over which raw methods can match which real methods. Example:

    sealed trait MethodType extends RpcTag
    class GET extends RestMethod
    class POST extends RestMethod
    
    @methodTag[MethodType](new GET)
    trait ExampleRawRpc {
      @tagged[GET] def get(@methodName name: String, @multi args: Map[String,Json]): Future[Json]
      @tagged[POST] def post(@methodName name: String, @multi args: Map[String,Json]): Future[Json]
    }

    In the example above, we created a hierarchy of annotations rooted at MethodType which can be used on real methods in order to explicitly tell the RPC macro which raw methods can match it. We also specify new GET as the default tag that will be assumed for real methods without any tag annotation. Then, using tagged we specify that the raw get method may only match real methods annotated as GET while post raw method may only match real methods annotated as POST. Raw methods not annotated with tagged have no limitations and may still match any real methods.

    Also, instead of specifying defaultTag in @methodTag annotation, you may provide the whenUntagged parameter to tagged annotation. Raw method annotated as @tagged[MethodType](whenUntagged = new GET) will match real methods either explicitly tagged with GET or untagged. If untagged, new GET will be assumed as the tag. This is useful when you want to have multiple raw methods with different whenUntagged setting.

    NOTE: The example above assumes there is a Json type defined with appropriate encodings - see encoded for more details on parameter and method result encoding.

    An example of real RPC for ExampleRawRpc:

    trait ExampleApi {
      def getUser(id: UserId): Future[User]
      @POST def saveUser(user: User): Future[Unit]
    }
    object ExampleApi {
      implicit val AsRawReal: AsRawReal[ExampleRawRpc,ExampleApi] = AsRawReal.materializeForRpc
    }
    BaseTag

    base type for tags that can be used on real RPC methods

  22. final class paramTag[BaseTag <: RpcTag] extends Annotation with RawMethodAnnotation

    Parameter tagging lets you have more explicit control over which raw parameters can match which real parameters.

    Parameter tagging lets you have more explicit control over which raw parameters can match which real parameters. This way you can have some of the parameters annotated in order to treat them differently, e.g. they may be verbatim, encoded in a different way or collected to a different raw container (e.g. Map[String,Raw] vs List[Raw] - see multi for more details).

    Example:

    sealed trait RestParam extends RpcTag
    class Body extends RestParam
    class Url extends RestParam
    class Path extends RestParam
    
    @paramTag[RestParam](new Body)
    trait RestRawRpc {
      def get(
        @methodName name: String,
        @multi @verbatim @tagged[Path] pathParams: List[String],
        @multi @verbatim @tagged[Url] urlParams: Map[String,String],
        @multi @tagged[Body] bodyParams: Map[String,Json]
      ): Future[Json]
    }

    NOTE: The example above assumes there is a Json type defined with appropriate encodings - see encoded for more details on parameter and method result encoding.

    The example above configures parameter tag type for the entire trait, but you can also do it for each raw method, e.g.

    trait RestRawRpc {
      @paramTag[RestParam](new Body)
      def get(...)
    }
    BaseTag

    base type for tags that can be used on real RPC parameters

  23. final class rpcMethodMetadata extends Annotation with MetadataParamStrategy

    @rpcMethodMetadata applied on metadata parameter of RPC trait metadata class indicates that this parameter holds metadata for RPC method(s) (one, some or all, depending on SymbolArity, tagging, etc.).

  24. class rpcName extends Annotation with RealSymAnnotation

    You can use this annotation on overloaded RPC methods to give them unique identifiers for RPC serialization.

    You can use this annotation on overloaded RPC methods to give them unique identifiers for RPC serialization. You can also subclass this annotation provided that you always override the name parameter with another constructor parameter.

  25. class rpcNamePrefix extends Annotation with RealSymAnnotation

    You can use this annotation on real RPC methods to instruct macro engine to prepend method name (or rpcName if specified) with given prefix.

    You can use this annotation on real RPC methods to instruct macro engine to prepend method name (or rpcName if specified) with given prefix. This annotation is mostly useful when aggregated by another annotation e.g.

    sealed trait RestMethod extends RpcTag
    final class GET extends RestMethod with AnnotationAggregate {
      @rpcNamePrefix("GET_") type Implied
    }
  26. final class rpcParamMetadata extends Annotation with MetadataParamStrategy

    @rpcParamMetadata applied on metadata parameter of RPC method metadata class indicates that this parameter holds metadata for RPC parameter(s) (one, some or all, depending on SymbolArity], tagging, etc.).

  27. final class tagged[Tag <: RpcTag] extends Annotation with RawMethodAnnotation with RawParamAnnotation

    Annotation applied on raw methods or raw parameters that limits matching real methods or real parameters to only these annotated as Tag.

    Annotation applied on raw methods or raw parameters that limits matching real methods or real parameters to only these annotated as Tag. See methodTag and paramTag for more explanation. NOTE: Tag may also be some common supertype of multiple tags which are accepted by this raw method or param.

    Tag

    annotation type required to be present on real method or parameter

  28. final class tried extends Annotation with RawMethodAnnotation

    When raw method is annotated as @tried, invocations of real methods matching that raw method will be automatically wrapped into Try.

    When raw method is annotated as @tried, invocations of real methods matching that raw method will be automatically wrapped into Try. Consequently, all real methods will be treated as if their result type was Try[Result] instead of actual Result. For example, if raw method is encoded and its (raw) result is Raw then macro engine will search for implicit AsRaw/Real[Raw,Try[Result]] instead of just AsRaw/Real[Raw,Result]

  29. final class verbatim extends Annotation with RpcEncoding

    Turns off raw value encoding as specified by encoded.

    Turns off raw value encoding as specified by encoded. By default, single and optional raw parameters are already verbatim, so using verbatim only makes sense on multi raw parameters or raw methods themselves, which means turning off encoding of method's result.

    When encoding is turned off, raw and real types must be exactly the same types. For example, the following raw RPC definition will match only raw RPC traits whose methods take Ints as parameters and return Doubles as values:

    trait VerbatimRawRpc {
      @verbatim def call(@methodName rpcName: String, @multi @verbatim args: Map[String,Int]): Double
    }

Ungrouped