Documentation

[jordaneremieff]

No description provided.

[jordaneremieff]

There are a few open issues that I think ought to be rolled into documentation generally: #31 #77 #39 #37.

Contributions in this regard are very much appreciated. Feel free to use this issue to post links to examples, discuss deployments, ask questions, submit doc PRs against, etc.

[iwpnd]

Hi, I stumbled upon your library because I wanted to deploy a fastapi application to AWS Gateway and Lambda.
During local development I would have a uvicorn server running at all times:

uvicorn example_app.main:app --reload

from fastapi import FastAPI
from mangum import Mangum

app = FastAPI()

@app.get("/ping")
async def pong():
    """
    Sanity check.
    This will let the user know that the service is operational.
    And this path operation will:
    * show a lifesign
    """
    return {"ping": "pong!"}

handler = Mangum(app)

Throws
RuntimeError: this event loop is already running.

It runs perfectly fine as it should in its deployment destination API Gateway / Lambda, yet not in local development. Setting enable_lifespan=False seems to work for both, but then I don't seem to understand the benefit of the default being true. Am I using it wrong in the first place? Should I only use lifespan if I want keep e.g. database connections open for the duration the Lambda is warm, whereas lifespan works as a kind of contextmanager that closes the connection when the Lambda goes cold?

[jordaneremieff]

@iwpnd Lifespan refers to an ASGI sub-specification, you can read about it here: https://asgi.readthedocs.io/en/latest/specs/lifespan.html. It isn’t related to AWS behaviour (side note: I should probably document this here specifically since this may be a source of continual confusion).

As to your specific issue, I haven’t attempted to reproduce it, but it looks like a conflict between Uvicorn and Mangum both trying to run the main async entry point.

If you’re running the application with Uvicorn locally, then it probably isn’t necessary to wrap it with Mangum. You can run the app directly with an ASGI server unless you’re using something like serverless-offline or another local AWS Lambda/API Gateway emulator.

[iwpnd]

It isn’t related to AWS behaviour

Thank you @ERM, that's the confirmation I was hoping for.

If you’re running the application with Uvicorn locally, then it probably isn’t necessary to wrap it with Mangum.

It is not necessary, you're correct. I was hoping there was a more elegant way than commenting out the handler for local development. I will read up on the lifespan sub-spec for ASGI as you proposed. It's probably just something I need to wrap my head around.

[iwpnd]

hi @ERM! I finished a little tutorial on how to deploy a fastapi with AWS Lambda/Gateway using Mangum. I mean it's not much, but I hope it helps some people to get started. Do you think I got the part about Mangum correct?

If this is still on your agenda, I would be happy to help with Mangum documentation or examples to get me started with contributions on Github.

[jordaneremieff]

@iwpnd had a read of your tutorial, good work! :)

Yeah, documentation is still on the agenda, though I'm not quite sure how it should look. Mangum itself doesn't do a whole lot that needs to be specifically documented (could be wrong). I think the most useful additions would be code examples/deployment configurations, but those vary quite a bit so I'm not sure how to best include them here.

Haven't had a lot of time to think about it lately, but I'm happy to review any PRs that could improve the docs - maybe something describing the lifespan behaviour would be a good start?

[allan-simon]

It is not necessary, you're correct. I was hoping there was a more elegant way than commenting out the handler for local development. I will read up on the lifespan sub-spec for ASGI as you proposed. It's probably just something I need to wrap my head around.

What I've done is the following , i have a lambda_main.py which only does :

from mangum import Mangum

from app import main

assert main.app is not None
handler = Mangum(main.app)

so that my main.py is what is launched by uvicorn (which therefore does not see the lambda_main.py code)

[allan-simon]

@iwpnd you tutorial was useful to me at least ! I'm deploying using terraform and gitlab-ci but it was of good help

the thing that your tutorial helped me clarify, and without I would have dismissed mangum, was the fact the .yml configuration seen in the examples was not needed (it was in these critical 5 minutes where you need to evaluate if a project is worth looking for, and at first I thought "oh damn a project with a configuration file and it's own set of command to package stuff etc." )

[jordaneremieff]

@iwpnd I've been revamping the documentation since I've had a bit more time as of late. If you'd still like to contribute, maybe you could start with a section that links to examples/guides. I don't know how it should look, but feel free to come up with a structure and add a link to your post and I'll review. I'm tracking this here #104.