coursera/naptime

Naptime is a Scala-based REST API framework built on the Play framework that enables developers to define resources and automatically generate corresponding GraphQL endpoints. It provides a comprehensive engine for handling data fetching, schema generation, and access control, while supporting complex features like query batching, complexity filtering, and deferred resolution. The system integrates tightly with Coursera's Courier and Pegasus data models to streamline serialization and schema inference.

39 changes.

This period marked the initial open-source release of Naptime, involving a major overhaul of the Courier integration, schema inference, and access control systems. It also introduced the Automatic Resource Inclusion (ARI) engine, enabling GraphQL support via Sangria with features like query batching and complexity filtering.

6 changes.

This period focused on enhancing the Naptime GraphQL engine by introducing a deferred resolver to batch and optimize API requests, alongside improved handling of nested and array-based identifiers. Significant effort was also dedicated to observability, adding middleware for metrics, slow query logging, and debug response metadata, supported by comprehensive test coverage for these new components and utility functions.

Introduces a new LocalFetcher component that allows the GraphQL engine to execute data requests directly against local Naptime resources (Engine2) without making external HTTP calls. This enables efficient, in-process data fetching by routing requests through existing Naptime routers, handling argument serialization, and managing headers to prevent body-parsing errors during internal execution.

naptime/src/main/scala/org/coursera/naptime/ari/fetcher · high confidence

The \KeyFormat\ system now supports \java.util.UUID\ as a resource key type, allowing resources to use UUIDs for identification. Additionally, a new \withFallbackReads\ method has been added to \KeyFormat\, enabling developers to provide alternative JSON reading logic that serves as a fallback if the standard key format fails to parse a value. These changes enhance flexibility in how resource identifiers are serialized and deserialized.

naptime-models/src/main/scala/org/coursera/naptime/model · high confidence

This change introduces a new example application built on the Play framework, demonstrating the integration of the Naptime API engine with the ARI GraphQL engine. It provides a complete reference implementation including Courier data schemas (Course, Instructor, Partner, User), Naptime resource definitions with GraphQL relations, and a GraphiQL interface for interactive query testing.

examples · high confidence

This change introduces the core components for the new GraphQL engine, replacing the previous implementation. It adds the \GraphqlSchemaProvider\ to manage schema caching and error handling, the \SangriaGraphQlSchemaBuilder\ to construct the GraphQL schema from Naptime resources, and the \SangriaGraphQlContext\ to pass request-specific data like fetchers and debug flags. Additionally, it includes the \NaptimeMarshaller\ for converting between Sangria's internal representation and Play JSON, and defines the \DataMapType\ scalar to support Pegasus DataMaps in GraphQL queries.

naptime-graphql/src/main/scala/org/coursera/naptime/ari/graphql · high confidence

The Naptime ARI engine now exposes a new GraphQLController that handles GraphQL requests via standard and batched endpoints. This controller integrates a configurable middleware pipeline (including metrics collection, slow logging, and response metadata) and supports query batching to allow multiple GraphQL operations in a single HTTP request. It also implements specific error handling for query analysis and syntax errors, ensuring structured error responses are returned to clients.

naptime-graphql/src/main/scala/org/coursera/naptime/ari/graphql/controllers · high confidence

The Naptime GraphQL engine now uses a new set of schema-building classes in the \schema\ package to construct the GraphQL type system. This includes \FieldBuilder\ for mapping data schemas to GraphQL fields, dedicated builders for resource fields (\NaptimeResourceField\, \NaptimePaginatedResourceField\, \NaptimeTopLevelResourceField\), and support for complex types like enums, records, and unions. The update also introduces \GraphQLRelation\ to parse relation annotations and \SchemaMetadata\ to manage resource and schema information, enabling more robust and modular schema generation.

naptime-graphql/src/main/scala/org/coursera/naptime/ari/graphql/schema · high confidence

The GraphQL controller now includes a filter mechanism to protect against overly complex queries. A new \QueryComplexityFilter\ analyzes incoming queries and rejects those exceeding a configurable maximum complexity score (defaulting to 100,000), returning an error response instead of executing them. This feature is implemented via a new \Filter\ trait and \DefaultFilters\ configuration within the filters package, allowing for extensible query processing.

naptime-graphql/src/main/scala/org/coursera/naptime/ari/graphql/controllers/filters · high confidence

Naptime now includes the foundational components for the Automatic Resource Inclusion (ARI) engine, enabling GraphQL-based access to Naptime resources. This change introduces the core data models in \models.scala\ (defining \Request\, \Response\, \FetcherApi\, and \SchemaProvider\ interfaces) and provides a \LocalSchemaProvider\ implementation in \LocalSchemaProvider.scala\ that derives the GraphQL schema from locally available Naptime routes. These additions establish the internal API layers for the new GraphQL presentation layer, allowing the engine to fetch and assemble data from unmodified Naptime APIs.

naptime/src/main/scala/org/coursera/naptime/ari · high confidence

The Naptime SBT plugin now includes a new \naptimeScaladoc\ task that extracts Scaladoc comments from source files (defaulting to \\*Resource.scala\) and writes them to a JSON resource file (\naptime.scaladoc.json\). This allows projects using the plugin to automatically bundle API documentation resources during compilation, as verified by the included scripted test.

naptime-sbt-plugin · high confidence

Three new middleware components have been added to the GraphQL controller layer to enhance observability and debugging. MetricsCollectionMiddleware now tracks field-level errors and query parsing times via a pluggable GraphQLMetricsCollector interface (with logging and no-op implementations). ResponseMetadataMiddleware, active only in debug mode, attaches source URLs, HTTP status codes, and error details to GraphQL response extensions for each field path. SlowLogMiddleware wraps the Sangria slow-log library to log queries exceeding a 6-second threshold, also respecting debug mode settings.

naptime-graphql/src/main/scala/org/coursera/naptime/ari/graphql/controllers/middleware · high confidence

Developers can now mix the new RestActionTester trait into their resource unit tests to easily invoke Naptime actions. This trait provides helper methods like testAction and testActionPassAuth, which streamline the process of executing actions with mocked authentication and request contexts, reducing boilerplate in test suites.

naptime-testing/src/main/scala/org/coursera/naptime/actions · high confidence

Added four new combinators to the Naptime access control system: \And\ (requires all controls to succeed), \AnyOf\ (allows the request if at least one control succeeds, exposing optional authentication data), \EitherOf\ (a right-biased combinator that prefers the right control's result), and \SuccessfulOf\ (allows the request if at least one control succeeds and exposes a set of all successful authentications). These new files in \naptime/src/main/scala/org/coursera/naptime/access/combiner\ provide developers with flexible ways to combine multiple \HeaderAccessControl\ instances to define complex authorization logic.

naptime/src/main/scala/org/coursera/naptime/access/combiner · high confidence

A new \DataMapUtils\ object has been added to provide utilities for ensuring that entire trees of LinkedIn \DataMap\ and \DataList\ objects are mutable. This addresses issues where read-only data structures caused failures, by recursively converting immutable structures into mutable copies during processing.

naptime/src/main/scala/org/coursera/naptime/actions/util · high confidence

The authentication system now supports more flexible error reporting and composition. When a header parsing error occurs, the system can now return a specific HTTP status code (defaulting to 401 Unauthorized) instead of always forcing a 401, allowing for more precise error responses. Additionally, the \Decorator\ trait now includes \map\ and \flatMap\ methods, enabling easier transformation and chaining of authentication logic. A new internal \authenticateAndRecover\ helper was also added to standardize error recovery during authentication attempts.

naptime/src/main/scala/org/coursera/naptime/access/authenticator · high confidence

The access control module now provides new combinators (AnyOf, And, EitherOf, SuccessfulOf) to compose authentication and authorization rules more flexibly. StructuredAccessControl has been refactored to use a shared Authenticator helper for error recovery and exposes a private check method, enabling direct validation of access control configurations in tests without requiring full HTTP request contexts.

naptime/src/main/scala/org/coursera/naptime/access · high confidence

The Naptime GraphQL engine now correctly resolves identifiers that are nested within arrays of records or wrapped in union types. A new utility module handles the iteration over data maps while respecting typed definition mappings, ensuring that paths like \/courses/instructorIds\ correctly extract IDs from complex nested structures. This change also adds robustness against null schemas and empty multiget lists, preventing null pointer exceptions during ID resolution.

naptime/src/main/scala/org/coursera/naptime/ari/engine · high confidence

The Naptime GraphQL engine now uses a new \NaptimeResolver\ to handle deferred data fetching, replacing the previous \NoopResolver\. This new resolver batches related resource requests by resource name and authentication override, merging multi-get requests to optimize performance and reduce the number of underlying API calls.

naptime-graphql/src/main/scala/org/coursera/naptime/ari/graphql/resolvers · high confidence

The Courier integration in Naptime has been significantly refactored to improve robustness and flexibility. The JSON serialization logic in CourierFormats has been rewritten to use a new CourierSerializer, which now calls the 'build' method on generated templates instead of 'apply' to align with Courier 2.0.8 changes, and introduces stricter validation that returns JsErrors rather than throwing exceptions during deserialization. A new CourierUtils object has been added to handle complex typed definition and union member conversions between Play JSON and Pegasus DataMaps, while StringKeyCodec has been updated to explicitly support primitive types (Boolean, Integer, Long, Float, Double) and Null values. Additionally, SchemaInference now supports WeakTypeTags and correctly handles None types, allowing for more flexible schema generation in generic contexts.

naptime-models/src/main/scala/org/coursera/naptime/courier · high confidence

This release introduces several changes to the Naptime framework core. ETags are now represented by a new \ETag\ type with a preference for weak validators, deprecating the previous \Strong\ validator. The \NaptimeModule\ now supports binding schema types via \bindSchemaType\, allowing developers to override inferred Pegasus schemas for specific data types. Error handling in \NaptimeActionException\ has been enhanced to support a \cause\ parameter for exception chaining and a new \withExceptionDetails\ method for adding structured debug information. Additionally, the \Fields\ class has been renamed to \ResourceFields\ to better reflect its role, and the \RequestEvidence\ trait is deprecated as it is no longer used.

naptime/src/main/scala/org/coursera/naptime · high confidence

The Naptime router2 module has been updated to align with Play 2.7, replacing the legacy \Action\ and \BodyParser\ types with \EssentialAction\ and \Accumulator\ in the routing components (\CollectionResourceRouter\, \NestingCollectionResourceRouter\). This change modernizes the request handling pipeline and updates request tagging to use \RequestAttrKey\. Additionally, the routing infrastructure has been refactored by extracting common data structures into a new \NaptimeRoutes\ component, which centralizes schema maps and router builders. The resource schema generation now includes \mergedType\ and \valueType\ fields, and resource attributes are populated via a new \AttributesProvider\ that loads Scaladoc metadata from a JSON resource file.

naptime/src/main/scala/org/coursera/naptime/router2 · high confidence

The Naptime schema definitions have been updated to improve type safety and flexibility. The \CustomBodyType\ union has been removed and replaced with explicit \TypeName\ fields (\inputBodyType\, \customOutputBodyType\) in the \Handler\ record, alongside a new \authType\ field. The \Resource\ record now distinguishes between \keyType\, \valueType\, and \mergedType\, and includes an \attributes\ array. Parameter handling has been enhanced with a new \typeSchema\ field for Pegasus data schemas, a \required\ boolean flag, and a shift from \JsValue\ to the new \ArbitraryValue\ union for default values, allowing structured arbitrary data. New Courier types \ArbitraryRecord\, \ArbitraryValue\, \AuthOverride\, \GraphQLRelationAnnotation\, \IncludedRelationAnnotation\, and \ParameterDataSchema\ have been introduced to support these changes.

naptime/src/main/pegasus · high confidence

The authenticator combiners (And, AnyOf, FirstOf) in the access control module now delegate authentication error handling to a new \Authenticator.authenticateAndRecover\ helper method, replacing the previous pattern of calling \Futures.safelyCall\ with manual \.recover(Authenticator.errorRecovery)\. This change centralizes how authentication failures are handled across combined authenticators, ensuring consistent error recovery behavior when evaluating multiple authentication strategies. Additionally, the visibility of the \And\, \AnyOf\, and \FirstOf\ traits has been tightened from \private\[access\]\ to \private\[authenticator\]\, restricting their usage to the authenticator package.

naptime/src/main/scala/org/coursera/naptime/access/authenticator/combiner · high confidence

The Naptime resource API now includes built-in helpers to reduce boilerplate when defining resources. A new \Fields\ accessor is added to the base \Resource\ trait, and \CollectionResource\ gains a \Nap\ method for constructing REST actions with default access control and parsing. Additionally, two new abstract classes, \CourierCollectionResource\ and \NestedCourierCollectionResource\, are introduced to automatically handle serialization and implicit requirements for Courier models, streamlining the setup for resources backed by Courier templates.

naptime/src/main/scala/org/coursera/naptime/resources · high confidence

The Naptime action builder now allows authentication logic to inspect the request body before deciding access, enabling authorization rules that depend on the payload content. This is achieved by introducing a new \AuthGenerator\ type that takes the parsed body and returns an access control result, and by adding a \DefinedBodyTypeRestActionBuilder\ that locks the body type to prevent later changes. The builder's \auth\ method now accepts this body-aware generator, and the \RestAction\ execution path passes the body to the generator during request handling. Additionally, the \NaptimeActionException\ constructor was extended to accept a \cause\ parameter, and serialization for \Option\ types was updated to handle \None\ values gracefully by returning empty content.

naptime/src/main/scala/org/coursera/naptime/actions · high confidence

The test helpers in the router2 package now correctly access the router builders via the \naptimeRoutes\ property instead of directly on the router object, ensuring that resource injection tests inspect the correct internal state. Additionally, minor formatting adjustments were applied to assertion statements in \RouterTestHelpers\ to improve code readability.

naptime-testing/src/main/scala/org/coursera/naptime/router2 · high confidence

Added ArgumentBuilder test helper for GraphQL argument construction; Added Courier schema definitions for test fixtures; Added Courier schema models for GraphQL ARI tests; Added test coverage for Courier model serialization and schema inference; Added test coverage for Naptime core components; Added test models for recursive schemas and custom ID fields; Added test suite for Naptime Courier integration and schema generation; Added tests for GraphQL query complexity filtering; Added tests for GraphQL schema provider and test models; Added tests for HeaderAccessControl combinators; Added tests for Naptime action utilities and refactored Engine2 test resources; Added tests for URL logging middleware behavior; Added tests for Utilities.getValuesAtPath; Added tests for the Decorator authenticator component; Added tests for the Naptime GraphQL schema engine; Updated router tests to align with Naptime 2.0 API changes.

The build system has been upgraded from Play 2.4.4 to Play 2.6.25, which includes updating the Play JSON library to version 2.6.14 and adjusting related dependency versions (such as Guice, Joda-Time, and ScalaGuice). Additionally, the project now includes a new 'graphql' subproject (naptime-graphql) that integrates the Sangria GraphQL library (version 1.4.2) and its slow-log middleware, alongside a new 'examples' subproject to demonstrate usage. The build infrastructure also adds support for publishing to Sonatype, license header checking, and code formatting via sbt plugins.

project · high confidence

The project has upgraded its default Scala version from 2.11.6 to 2.12.10, while maintaining cross-compilation support for Scala 2.11.11. Several library dependencies have been updated, including Shapeless (2.2.5 to 2.3.2) and the Play sbt plugin (to 2.4.4). The build configuration also introduces \scalafmtOnCompile\ for code formatting and adds dependency overrides for \playJson\ to ensure version consistency across modules.

(dependencies) · high confidence

Initial open-source release of Naptime version 0.11.8; Update Javadoc formatting in Pegasus codec classes.

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 48.

• Code Health 90
• Architecture 98
• Maturity 36
• Readiness 33
• Security 78

• 253 commits — 220 feature/other, 33 fixes

• (root) — 75 commits
• naptime/src — 69 commits
• naptime-graphql/src — 62 commits
• naptime-models/src — 18 commits
• naptime-testing/src — 11 commits
• examples/src — 5 commits
• project/NaptimeBuild.scala — 5 commits
• (repo) — 3 commits
• naptime-sbt-plugin/src — 2 commits
• naptime-pegasus/src — 1 commit
• naptime-testing/build.sbt — 1 commit
• project/plugins.sbt — 1 commit

• fix: Bugfix: Ensure datamap & contents are mutable. (#51)
• fix: Bumping up version to fix partial naptime release
• fix: Engine2 Fix: Successfully reproduced & fixed bug (#52)
• fix: Fix Re-ordering of Related Resource Ids (#236)
• fix: Fix start pagination for non-string fields (i.e. ints) (#154)
• fix: Fix test in root project. (#17)
• fix: Fix bad rebase, take 2 (#250)
• fix: Fix bug with aliases on top-level resources (#112)
• fix: Fix bug with field names for enum fields (#139)
• fix: Fix bug with variables in query execution (#140)
• fix: Fix bugs with generating and resolving union types (#143)
• fix: Fix compile breakage. (#108)
• fix: Fix enum fallback (#153)
• fix: Fix flaky naptime test by adding IntegrationPatience (#231)
• fix: Fix for optional fields being null (#131)
• fix: Fix fragment parsing and __id generation (#111)
• fix: Fix interpolating into nested ids which requires the original DataMap to be kept using passthroughEnabled flag (#242)
• fix: Fix license. (#8)
• fix: Fix multiget fields (#191)
• fix: Fix naming bug with enumField inside unionField (#146)
• …and 233 more

• 0 containers · 3 bounded contexts · 4 dependency edges (baseline)

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

coursera/naptime was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.