Channels

[Netzvamp]

I would love to implement channels into genesis. That way we could address each leg of a call or a newly originate call with it's own uuid. We could filter by channels and get clean separated events for every freeswitch phone/user. And we could also get new channel objects out of inbound connections. Currently we filter by "Unique-ID" header with myevents, but that way we only separate events by sessions, not by channels/legs. And myevents prevents to ever get events with different "Unique-ID"s, so originate a new channel is nearly impossible.

(I never use myevent in my stuff and manuell use filter to add known UUIDs, then i can originate a call and can handle this call parallel to the initial call. That could be the default, so we could create new channels by manually set UUIDs and filter them.)

With channels we could implement very pythonic APIs(dummy code, don't care to much about syntax 😉):

• Playback on the inbound channel (A leg) while originating a call in the background, play this new call a audio file and then bridging them together:

session.channel.playback("myfile", blocking=False)
new_channel = session.originate("my origination dial string")
new_channel.playback("myfile", blocking=True)
result = session.channel.bridge(new_channel, <options>)

• Get b leg channel from dialstring: result, channel_b = session.channel.bridge("dialstring", <options>)
• Pythonic inline channel creation: result = session.channel.bridge(session.originate("my origination dial string"), )`
• Play different sounds on each channel:

await channel_a.playback("tone_stream://%(1000,4000,425);loops=-1", blocking=False)
await channel_b.playback("myfile.way", blocking=False)

This might be a more logical way to handle what happens to which call member and when.

I've already implemented something like that into my own library and would love to get this to the genesis level.

The problem is with API compatibility. It would definitively break something.

[Netzvamp]

I've moved that from the "Merging inbound/outbound methods" discussion to here. Both are related in the way that if we implement channels we break the API, so we can also break connection handling API by merging inbound/outbound 😀

[Otoru]

I really like this idea, this level of control would be really nice to have and I think it would be worth the risk of adding some breaking changes to the lib.
I confess that I have never taken an approach like the one you suggested for doing the event filter and I would love to see it. I think this is something that is really worth putting effort into.
I think the first step is to determine what a channel will actually be and how it will be implemented.

[Netzvamp]

Ok, i'll start a new branch (v2 or something that indicates API changes) and implement it there.

I could also port some stuff of my library to genesis:

• I've integrated a fastapi server for some webinterface and HTTP API. More dependencies but very useful stuff:
  • A event viewer for inbound and outbound event. It's much easier to track events in a webinterface with a propper filter function
    
  • API for basic call control like mute, transfer, hangup
    
  • API to get some freeswitch basics like current calls and basic infos
  • The API is extendable by the user to get his own endpoints with his own call handler (for example the call guide endpoint in the screenshot was from a user handler)
• separate functions by freeswitch modules for better code readability and documentation (logical links to freeswitch documentation): mod_commands, mod_event_socket and mod_dptools should be separate python modules. That way extending is easier, cause it's clear where to put it.
• implement freeswitch applications like mod_conference in seperate modules
• Future possibilities:
  • A high level and a low level API: At high level nobody needs to know that a session is a call leg and how freeswitch works. Heavy abstraction that just works. At low level you get all the freeswitch stuff with fine grained control but it is more complex.

I would really love to scrap my library and in favor of genesis.

[Otoru]

Contributions are always welcome, but we just need to make sure they don't harm the scope of the project.

My goal with Genesis is to enable this level of abstraction in the work, but not to do all the work. The idea is for it to be a framework for developing apps for FreeSwitch and not an application in its own right.

So having APIs at the code level for fine-grained call control could be interesting, but we're not going to actually implement a web server that does this.

[Netzvamp]

Still work in progress, but i wanted to show you what i have so far: https://github.com/Netzvamp/Genesis/tree/channels

Look at the examples, especially the outbound_originate.py: https://github.com/Netzvamp/Genesis/tree/channels/examples

That shows the flexibility of the approach: We can answer, do playback, originate a second channel that gets a playback before we bridge them together. Then we unbridge them again to play every leg a different file and then bridge them again together.

It's possible with current genesis, but the python dialplan would be a mess 😉

There are still many things to do:

• bgapi for most of the api calls for more async behavior. For originate this is a must
• more and better exceptions and hangup detection
• mod_conference implementation
• Example that rebuilds fs_ctl in python
• Update tests
• Update cli tools
• implement spy/evesdrop
• We should generate a doc with Sphinx, maybe add some pages with examples and tutorials. We should look how we could build that into github actions.
• Add a router to send calls to different handlers based on call variables (destination number)

There may be some breaking changes, but i can't tell since my code base is already migrated.

I don't have a timeline yet for the todos but i'll update you here.

So, what do you think?

[Otoru]

About the docs: I currently use the github wiki, but I'm going to migrate this to a new model to allow contribution.
About the router, I like this, maybe something like the flask blueprints, with priority o regex.

[Otoru]

Just2Share:
Now we use hugo to generate docs: https://otoru.github.io/Genesis/

[Netzvamp]

I've also got the tests back to running. I had to be very explicit by stopping everything step by step in genesis and the Mockserver. This helps not only in the tests, where we create and destroy many instances, but also in production. But there is more to do with tests, more coverage for example.

[Netzvamp]

Just2Share: Now we use hugo to generate docs: https://otoru.github.io/Genesis/

Sphinx could generate a documentation based on the docstrings in the code 🤓

[Netzvamp]

Since i've already implemented breaking changes, i can continue with that 😉

After bgapi i looked more into async and how to handle tasks.

Using a block parameter in an async library is generally not a good idea and does not conform to standard practices in the Python asyncio ecosystem.

• Convention: Standard async libraries (like httpx, asyncpg) return an awaitable (a coroutine or a future-like object) that represents the entire operation. The user decides when to wait for the result by using await. The library itself does not offer a parameter to change its internal awaiting behavior.
• Clarity: The block parameter creates a confusing API. A user must always await the method call (e.g., await session.playback(...)), but what that await does changes based on the block flag.
  • With block=True, the await waits for the command to be sent and for the operation to complete on the FreeSWITCH side.
  • With block=False, the await only waits for the command to be sent. The user then receives a CommandResult object that must be awaited a second time to ensure the operation is complete. This dual behavior for a single await is unintuitive.

## Before:

# Fire off the command and get a future-like object
result_future = await channel.playback("file.wav", block=False)
# Do other work...
# Wait for the command to complete later
await result_future

## After:

# Create a task to run the command in the background
playback_task = asyncio.create_task(channel.playback("file.wav"))
# Do other work...
# Wait for the task to complete later
result = await playback_task

## General handling example:

# Create a task to run the operation in the background
task = asyncio.create_task(long_running_operation())

# Loop until the task is done, checking periodically
while not task.done():
    print("Checking task status... not done yet.")
    # Yield control to the event loop for a short time
    await asyncio.sleep(0.5)

print("Task is complete!")

# Safely get the result after the task is done
result = await task
print(f"Result: {result}")

There are many more async task managing methods usable to execute these task in different ways:
gather, Queue, PriorityQueue, LifoQueue, TaskGroups, wait, wait_for, as_completed

I think it would be a benefit to remove the block parameter for clarity and standard compliance with python and other libraries.

[Otoru]

This parameter exists to make migration between genesis and other libs (like greenswitch) friendly, but you brought up some good points.
I would be willing to make this change if I were to go for an approach like the one in these examples.

[Netzvamp]

Nice! I think since we'll have the most pythonic freeswitch library by far, python standards are more important than compatibility to freeswitch libraries that don't have near the features our lib has. I'm very exited to release this when it's done, i think there will be no way around genesis for freeswitch users 😁

[Otoru]

I made a significant improvement to the project, which also includes the beginning of a channel abstraction for inbound and outbound connections. This is just the start of what we had in mind and can certainly be improved. I'm closing this topic because some time has passed and we haven't had any interactions, but each suggestion for improvement to the new abstraction can become a new topic or a pull request for the project.

[Netzvamp]

I'm also prepairing channels abstraction. What i've done some months ago is to incompatible with the current master branch, so i've redone it and made it a optional addon API that doesn't interfere with existing API. My plan is to test it tomorrow in real life conditions and make a pull request next week.
I know it looked like i've abandoned the idea, but i just hadn't the time for this project, but now i have to make progress with it.