DOCSEARCHbyAlgolia
Submit Docs

ServiceTalk Documentation

repository·main·Indexed 21 days ago

https://github.com/apple/servicetalk

A high-performance JVM network application framework built on Netty for service-to-service communication. It supports various protocols, smart client features like load balancing, and a 'Blocking Safe by Default' model that manages thread offloading from the event loop. Includes implementations for the gRPC Health Checking v1 Protocol and utilities like AsyncContext and CapturedContext for state propagation and ThreadLocal interoperability.

Tokens
36.1K
Snippets
60
Records
191
Agent score
75%

What's inside ServiceTalk

  1. Overview of the Serialization API

    main
    The servicetalk-serialization-api module provides a technology-agnostic API for serialization and deserialization. It defines the common interfaces and abstractions used throughout ServiceTalk to handle data conversion, allowing users to work with serialization logic without being tied to a specific underlying technology (such as JSON, Protobuf, or others).

  2. What is ServiceTalk?

    main

    ServiceTalk is an extensible networking abstraction layer built on top of lower-level networking frameworks like Netty. It is designed to simplify service-to-service communication by addressing common challenges found in low-level frameworks, such as complex threading models, difficult usability for application-level use cases (like RPC or request/response), and missing high-level features.

    Key improvements over low-level frameworks include:

    • Managed Threading Model: Handles the complexities of asynchronous non-blocking I/O internally, reducing the need for manual thread hops when executing CPU-intensive or blocking code.
    • Application-Tailored APIs: Provides APIs designed for common use cases like HTTP/1.x, HTTP/2, and gRPC, rather than just low-level primitives.
    • Smart Client Features: Includes built-in support for load balancing, service discovery, retries, and circuit breaking.
    • Simplified Error and Back-pressure Handling: Provides more intuitive error propagation and manages back-pressure between data sources and sinks.

  3. Overview of ServiceTalk

    main

    ServiceTalk is a JVM network application framework built on top of Netty. It provides high-performance, scalable networking APIs tailored to specific protocols (such as HTTP/1.x and HTTP/2.x) for service-to-service communication.

    Key features include:

    • Server support for various protocols.
    • "Smart client" capabilities, including client-side load balancing and service discovery integration.
    • Support for multiple programming paradigms.

    ServiceTalk follows Semantic Versioning (SemVer 2.0.0). Note that 0.x.y releases are considered unstable and may contain API/ABI breaking changes.

  6. Use ServiceTalk Data Protobuf Jersey for Protobuf serialization

    main

    The servicetalk-data-protobuf-jersey module enables Protobuf serialization and deserialization within the ServiceTalk Jersey router.

    Key capabilities include:

    • Skipping InputStream conversions for improved performance.
    • Direct serialization of Single<MessageLite> and Publisher<MessageLite> from resource methods.

    Important Note on Encoding: When using Publisher<MessageLite>, the module utilizes Base 128 VarInt Encoding for the serialized data.

  8. Use Security (Jersey router) for JAX-RS authentication

    main

    The servicetalk-http-security-jersey module provides JAX-RS filters that set javax.ws.rs.core.SecurityContext for requests authenticated via various schemes. This allows your JAX-RS resources to access authentication information through the standard SecurityContext API.

    Jersey 3.X Compatibility

    If you are using Jersey 3.X, you must replace all javax.ws imports with jakarta.ws and use the appropriate dependency:

    • For Jersey 3.0.X: servicetalk-http-security-jersey3-jakarta9
    • For Jersey 3.1.X: servicetalk-http-security-jersey3-jakarta10

  9. Use Protobuf serialization with ServiceTalk Jersey

    main

    The servicetalk-data-protobuf-jersey module enables Protobuf serialization and deserialization for the ServiceTalk Jersey router.

    Key features:

    • Bypasses InputStream adaptation used by standard body readers for better performance.
    • Allows resource methods to accept or return Single<MessageLite> or Publisher<MessageLite> directly.

    Limitations:

    • This serializer cannot currently be used with Server-Sent Events (SSE).

    Content Encoding Types:

    • Single Item Encoding: Uses application/x-protobuf for Single and plain-old-protobufs.
    • VarInt Encoding: Uses application/x-protobuf-var-int (base 128 VarInt protobuf encoding) for Publisher streams.

  12. Preview of future load balancing capabilities

    main

    The ServiceTalk load balancer is designed to support advanced features in future updates:

    • Weighted Load Balancing: Allows explicitly accounting for backend capacity (e.g., different hardware) by propagating weight information via ServiceDiscoverer or control-plane support.
    • Priority Groups: Enables partitioning backends into groups with relative priorities. The load balancer uses higher-priority groups first, maintaining a minimum number of healthy backends in lower-priority groups as backups.
    • Subsetting: Reduces connection overhead in large clusters by only maintaining connections to a specific subset of backends rather than a full mesh.