This way, fetching a service instance inside a resolver is very straightforward:
`typescript
@Query(returns => [Book])
async books (@Ctx() ctx: Context) {
return await ctx.svc(BookService).fetchAll()
}
`

Services

To help you organize services this way, this library provides a BaseService abstract class. The most important thing it provides is the Context object we discussed earlier. Anything extending BaseService will have a this.ctx property for easy access to the context without having to constantly pass it from your resolvers.

`typescript
const bookLoader = new PrimaryKeyLoader({
fetch: (ids: string[]) => await getBooks(ids)
})

class BookService extends BaseService {
async findById (id: string) {
return await this.loaders.get(bookLoader).load(id)
}
}
`

You might notice above that I used this.loaders instead of this.ctx.loaders, totally contradicting what I stated above. Well, for convenience, BaseService passes applicable methods through to its context, to save you a little bit of typing:

* this.svc for access to other models' services, a tiny bit easier than this.ctx.svc
* this.loaders for your dataloader-factory instance, a tiny bit easier than this.ctx.loaders
* this.auth for the user object provided by authentication, over this.ctx.auth
* this.timing for development logging, over this.ctx.timing
* this.requireAuth to interrupt execution and signal the UI that the user needs to log in

So when you need access to data, no matter whether you are in a resolver or another model's service, you can obtain the service of your choice from the context.

$3

The JWT base64 encoded secret can be provided in the JWT_SECRET environment variable. If you are using asymmetric signatures, you can put the public key in JWT_SECRET_VERIFY (this library does not make use of the private key). If both environment variables are set the asymmetric JWT_SECRET_VERIFY key is used.
`bash


Examples of how to create keys for context jwt tokens

Query digests are a sha256 hash of the client service name/id and a query string. This digest is then bundled as the qd field in the JWT payload, which is signed by a private key for approved queries. The private query digest key is never shared or accessed by the client service. The private key is only used to sign approved queries. The JWT that is generated may then be checked into the repo. When the client service needs to make a request to the graphql service it will send the associated query digest JWT in the x-query-digest http header along with it's client_id service name JWT in the authentication header and query string in the body.

When the graphql-server sees a request with query scoping turned on, it will first verify the JWT authn token and pull the client service name found in the client_id field of the authentication payload. The client service name is then hashed with the query sent in the body of the request to generate a query digest. It is then matched to the qd hash found in the signed query digest token that was also sent by the client service in the x-query-digest header. If it is a match the query is indeed allowed by this client service and may be processed.
`bash


Examples of how to create keys used for query digest jwt tokens

Query scoping allows for some clients to be whitelisted and not require query digest with their requests. Use the graphql-server signedQueriesWhitelist: Set option to contain a collection of the client service names excluded from Query scoping.

If you need to support cookies or tokens in the query string or any other sort of scheme, you can subclass the provided Context class, override tokenFromReq (to retrieve the JWT) or authFromReq (to do all the extraction and validation yourself), and pass your subclass in as a configuration option:
`typescript
import { GQLServer, Context } from '@txstate-mws/graphql-server'
class CookieContext extends Context {
tokenFromReq: req => req.cookies.token
}
const server = new GQLServer({ ... fastify configuration })
server.start({
...,
customContext: CookieContext
})
`
authFromReq, if you write it, should return an object for ctx.auth or undefined if authentication could not be established (do NOT return an object with an empty user id!). It can be async or return a promise if you need to do a lookup, like searching a database for a session id.

Keep in mind that if you add brand new methods to your custom Context class, you'll need to reference your class in every resolver after @Ctx():
`typescript
@FieldResolver(returns => [Author])
async authors (@Ctx() ctx: CustomContext, @Root() book: Book) {
// return the authors
}
`
If all you've done is replace authFromReq or tokenFromReq, this isn't necessary because all the types are compatible and the context object you'll receive will still be an instance of whatever you passed as customContext.


$3

Your clients will be able to detect an authentication problem by checking whether errors[0].authenticationError in the response data is true. They may need to redirect their user to a login screen.

Authorization

This library provides a completely opt-in AuthorizedService abstract class that you can use instead of BaseService.

Each AuthorizedService may provide a mayView method that accepts an instance of the model associated with the service and returns true only if the current authenticated user should be able to view the object. This is how we implement complex user-based authorization for each data type.

Additionally, each service may provide a non-mutating removeProperties method that accepts an instance of the model and removes or anonymizes one or more properties from the object before returning it. Do NOT mutate the input object, it will be in the dataloader cache and shouldn't be altered. Return a cloned object instead.

Finally, AuthorizedService provides a removeUnauthorized method that your service may use to clean out objects the user shouldn't see. It calls mayView and removeProperties on each array element and filters out objects and properties the authenticated user should not see. It should be used every time a service method returns an array.

There's nothing here for authorizing mutations; that should generally take place at the beginning of the mutation method in the service class, but can also be broken out into helper methods like mayCreate or mayDelete.

$3

export class BookService extends AuthzdService {
async mayCreate () {
return await isUserAnAdmin(this.auth.username) // this.auth.username is typed as a string
}
}
`
This is also a great way to add more authorization-related helper methods like fetchCurrentUser or isLibraryOwner for use in multiple services.


Timing

What this library encourages is to split your errors into unexpected system errors and expected validation errors. Unexpected errors happen when the infrastructure is offline or a developer has made a mistake (either an API developer or a UI developer). Those errors get thrown and end up in the errors array.

Expected errors happen when a user makes a mistake, like specifying a date outside the allowed range. These errors should not be in the errors array at all. Instead, we should allow for the possibility of an error in the response.

This library provides a ValidatedResponse type for this purpose. A ValidatedResponse has a success property to indicate whether the mutation took place or was rejected without altering any state. It also has a messages property with messages to be presented to the user. Each message has a type: error, warning, or success, and an arg identifying the mutation argument that caused the message. arg may be dot-separated or in bracket notation when one of the arguments is an object and the error is deep inside it.

Note that there can be messages even when success is true. Messages with type success are to let the user know that they did something well; for example, the password they've entered is strong. Messages with type warning warn the user about something, but allow the mutation to complete anyway.

The arg should always identify the GraphQL argument that caused the error. For instance, createUser(username: 'Hamburger') might reply with a message that looks like { message: 'That is not a name for humans!', type: 'error', arg: 'username' }.

To use a ValidatedResponse, simply create and return one during the course of servicing a mutation. Note that you often want to collect validation errors instead of returning immediately, so that you can communicate to users about all the things that went wrong all at once instead of hitting them with a new one each time they resolve something. You can use the hasErrors method to determine whether one or more errors occurred.
`typescript
class UserService extends BaseService {
async registerForClass (section: Section) {
if (!await userAllowedToRegister(this.auth.username, section)) {
return ValidatedResponse.error('This user cannot register for this course.')
}
const response = new ValidatedResponse()
if (!await sectionHasAvailability(section)) {
response.addMessage('This course is full.', 'section', 'error')
}
if (!await sectionHasAnInstructor(section)) {
response.addMessage('This course has no instructor yet.', 'section', 'error')
}

if (!response.hasErrors()) {
await registerUserForSection(ctx.auth.username, section)
response.success = true
}
return response
}
}
`


$3

constructor (args: ValidatedResponseArgs & { book: Book }) {
super(args)
this.book = args.book
}
}
`


$3

When NODE_ENV is set to development, the request log is mostly disabled, only printing the response time and query for each. Errors will be logged directly to the console instead of in JSON format, for much better readability with proper line breaks.

Federation

For instance, a user is a concept shared by most applications, so calling it User everywhere is probably ok. However, something named Rule is highly likely to exist in multiple systems and mean something totally different in each one. Try to prefix generic type names with the name of the application so that you won't have to jump through hoops to transform your API for federation.

$3

To provide support, first add @Directive('@key(fields: "id")') as a decorator of your model class, where "id" is a space-separated list of fields involved in the primary key.

Then you'll need to provide a reference resolver function. The gateway is going to send a "stub" object (an object containing all the fields from at least one of the @key directives you specified) as the parent, and you need to transform that stub object into the regular object.

To support this, graphql-server provides a @ResolveReference('TypeName') decorator that you can use to decorate your resolver function. Your resolver function is NOT a regular resolver. Do NOT decorate it with @FieldResolver or use the argument decorators like @Ctx() or @Root(). Just use the standard graphql resolver signature async function (root: YourTypeStub, args: any, ctx: Context, info: GraphQLResolveInfo) => YourType.

It's probably most convenient to place it with your field resolvers (just remember it's not one).
`typescript
@Resolver(for => Book)
export class BookResolver {
@Query ...
... query resolver ...

@ResolveReference('Book')
async resolveReference (stub: { id: number }, _args: any, ctx: Context) {
return await ctx.svc(BookService).findById(stub.id)
}
}
`
Entity resolution queries will arrive from the gateway in large batches and your resolveReference functions will all be run concurrently. Use dataloader as normal to maintain good performance.

Note: for now ResolveReference requires you to hand it the type name. Maybe in the future it'll be able to figure it out automatically.

#### Advanced Primary Keys
It's also possible to support multiple primary keys and nested primary keys. See https://www.apollographql.com/docs/federation/entities/ for more detail. Keep in mind that your resolveReference resolver must detect which kind of stub has been provided and perform its lookup appropriately.

$3

The Library type needs a books property that returns books from the book service. We do this by creating an array of "stub" books in our graph that act as stand-ins for the full book objects. The federation gateway will be responsible for fetching the full objects.

First, create a type for the stub:
`typescript
@Directive('@extends')
@ObjectType()
export class Book {
@Directive('@external')
@Field(type => Int)
id!: number
}
`
The @extends directive lets the gateway know that we don't own this type and we need its help to fetch it. You must add the @extends directive even if you are not adding any new properties to the type (see below for more on that).

The @external directive lets the gateway know which fields belong to another graph. All the fields involved in another graph's @key directive should be listed on your stub and marked external. If you have any fields not marked external, the gateway will add them to the federated graph and assume that you are responsible for filling them with data (see below section for more).

Then create a resolver that creates stubs:
`typescript
@Resolver(of => Library)
export class LibraryResolver {
... other resolvers ...

@FieldResolver(returns => [Book])
async books (@Ctx() ctx: Context, @Root() library: Library) {
const bookIds = await ctx.svc(LibraryService).getBookIdsForLibrary(library)
return bookIds.map(id => ({ id }))
}
}
`
Since we returned an object compatible with our Book stub above, the federation gateway will be able to fill out the stub with the rest of the book details and connect us with all the other Book field resolvers in other services.

$3

Since the library service owns all the data that links libraries to books, the library service must implement this resolver, even though the library service does not own the Book type.

Since the gateway will need to come to you to get properties filled out, you'll need to add the @key directive to your extended stub so that the gateway knows which fields to send to you.
`typescript
@Directive('@extends')
@Directive('@key(fields: "id")')
@ObjectType()
export class Book {
@Directive('@external')
@Field(type => Int)
id!: number
}
`
Then you need to add a resolver for each of the extra properties.

If you have any new scalar properties, you can choose to provide a reference resolver with @ResolveReference, as you learned to do above, or you can list all the new properties as field resolvers, and dataload in your table row in each one. That's up to you, but @ResolveReference is probably easier in general.

#### Using the @requires directive
If you are adding a property, and you need another property on the same type from another graph, you can use the @requires directive to make sure the gateway sends it to you.
`typescript
@Resolver(of => Book)
export class BookResolver {
@Query ...
... query resolver ...

@Directive('@requires(fields: "isbn")')
@FieldResolver(returns => Float)
async amazonPrice (@Ctx() ctx: Context, @Root() bookstub: Book) {
return await ctx.svc(AmazonService).getBookPriceByISBN(bookstub.isbn!)
}
}
`
Keep in mind that any field you require must be listed in your stub model as @external.
`typescript
@Directive('@extends')
@Directive('@key(fields: "id")')
@ObjectType()
export class Book {
@Directive('@external')
@Field(type => Int)
id!: number

@Directive('@external')
@Field()
isbn?: string
}
``
This is so that the federation gateway can validate that the type of data you require still matches what will be provided in the host service. You may think this check is unnecessary, but Apollo Gateway will fail to validate so you don't have much choice.

Something else in this example was a little tricky. The isbn CANNOT be marked as nullable for graphql, because the original type does not mark isbn as nullable and they must match. However, it needs to be marked optional for typescript so that you can make stubs (since you don't have the isbn when making a stub). When you implement your resolver, you'll have to use an exclamation mark (as in the example above) to assure typescript that the gateway will have provided it.

$3

$3