Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add event entities #44

Merged
merged 3 commits into from Jan 8, 2017
Merged

Add event entities #44

merged 3 commits into from Jan 8, 2017

Conversation

@SuperTux88
Copy link
Member

SuperTux88 commented Dec 31, 2016

@annando and me discussed federation of events at the 33C3 and this is the result of it.

We need two new entities for this: Event and EventParticipation (I added the specification for it also below in the description, so you don't need to read the markdown in the diff :) ).

  • The Event entity is attached to the StatusMessage entity and contains all needed informations about the event.
  • The EventParticipation entity is sent as relayable if somebody accepts or declines the event.

Some additional thoughts that came to my mind while writing the docs:

  • Should we also add a created_at and public property to the Event entity, if we want to send the event as single entity without StatusMessage?
    Photo has this currently, but it is not used. Personally I think this isn't needed now, we can always add this later when we need it. If attached to a StatusMessage we can use the values from there.
  • Should we also add Event as an optional property to the private Message?
    This can be useful if we want to invite people without making an aspect for them. I think this is useful and doesn't hurt us.

This is needed for diaspora/diaspora#1359


Event

This entity represents an event.

Properties

Property Type (Length) Description
author diaspora* ID The diaspora* ID of the author of the event.
guid GUID The GUID of the event.
summary String (255) The summary of the event.
start Timestamp The start time of the event (in UTC).

Optional Properties

Property Type (Length) Description
end Timestamp The end time of the event (in UTC). If missing it is an open-end or a single all_day event.
all_day Boolean true if it is an all day event. Time/timezone is ignored. false by default.
timezone Timezone If the event is fixed to a specific timezone, this can be set. The start/end timestamps are then displayed in this timezone. This is useful for local events. If missing or empty the timestamps are displayed in the timezone of the user.
description Markdown (65535) Description of the event.
location Location Location of the event.

EventParticipation

This entity represents a participation in a Event.

Properties

Property Type Description
author diaspora* ID The diaspora* ID of the author of the event participation.
guid GUID The GUID of the event participation.
parent_guid GUID The GUID of the Event.
status String The participation status, lowercase string as defined in RFC 5545, Section 3.2.12 (accepted, declined or tentative).
author_signature Signature The signature from the author of the event participation.
parent_author_signature Signature] The signature from the author of the Event.
@SuperTux88 SuperTux88 requested a review from denschub Dec 31, 2016
@muggenhor

This comment has been minimized.

Copy link

muggenhor commented Jan 1, 2017

I would just use iCalendar (RFC 5545), or a subset there-of. At least for the field definitions, if not for the storage format. That way the semantics are most likely to be compatible with other calendaring software. RFC 6321 provides for a way to store this as XML. But regardless of the serialisation format chosen conversion will stay necessary.

The semantics and naming conventions of iCalendar are most important. Specifically author would be ORGANIZER, guid UID, start DTSTART, etc.

@SuperTux88

This comment has been minimized.

Copy link
Member Author

SuperTux88 commented Jan 1, 2017

We oriented us on iCalendar for the names, but I think it is more important to be consistent with the other federated entities. It would be weird if it is organizer here and author everywhere else, same with guid. We could use dtstart instead of start, but I don't see much benefit in it (It is another format anyway and I think the simple start looks nicer). But we used start and not begin so it is simpler to create a mapping (maybe for an export with iCal format).

This format is used for communication between servers talking the diaspora protocol. It isn't compatible with anything else using iCalendar directly anyway, because of the surrounding salmon with signature.

Also this isn't about storage (that's up to everyone), and diaspora has another DB structure than friendica. And if you want to use it in another calendar software, you'll need an export from this storage format to iCal, but that is out of scope here, because the federation protocol is multiple layers away from being used in other calendar softwares.

About the XML format: We don't need simply XML, it needs to be a special XML structure:

<entity_name>
  <property1>value1</property1>
  <property2>value2</property2>
</entity_name>

And the format described in RFC 6321 doesn't match this format.

@muggenhor

This comment has been minimized.

Copy link

muggenhor commented Jan 1, 2017

Right, so this is just the wire protocol for federation of events? I thought it might also be used (in an altered form) for communication with clients. Thanks for clearing that up.

Mostly what I'm concerned with is that whatever choices are made here don't make it impossible to convert back and forth to iCalendar without ambiguities.

@@ -85,6 +85,12 @@ An [ISO 8601][iso8601] date.

Example: `2016-02-19`

## Timezone

A timezone in the form `Area/Location` as used in the [Time Zone Database][tz].

This comment has been minimized.

Copy link
@muggenhor

muggenhor Jan 1, 2017

Is this for display purposes only? I.e. is the timestamp itself still stored as UTC? Otherwise it's too easy to do the wrong thing with the timestamp.

And if it is used only for display purposes then why not use the location for that purpose (to show local time), or the timezone of the computer used by the client displaying this?

This comment has been minimized.

Copy link
@SuperTux88

SuperTux88 Jan 1, 2017

Author Member

The timestamp is stored and federated in UTC. This is used to display the time in this timezone, and if not set it is displayed in the timezone of the viewer.

That is useful if you have a local event (birthday party at your home) and a friend from another country/timezone sees this event always with the timezone you set (the timezone of your home).

If not set, it's displayed in the timezone of the viewer, useful for a livestream or something like that, so you see when the event is in your timezone.

I don't know if it is reliable to use the location for that, I think it is better to set the timezone explicitly instead of doing some location magic.

This comment has been minimized.

Copy link
@SuperTux88

SuperTux88 Jan 1, 2017

Author Member

This is based on a feature friendica already has: You can set something like "convert time to viewer timezone" (I don't remember the exact wording), so we decided to make this the default if no timezone is added and add the organizer timezone if it should be displayed always in this timezone.

@SuperTux88

This comment has been minimized.

Copy link
Member Author

SuperTux88 commented Jan 1, 2017

Right, so this is just the wire protocol for federation of events?

Yes, and communication with clients is a completely different thing.

Mostly what I'm concerned with is that whatever choices are made here don't make it impossible to convert back and forth to iCalendar without ambiguities.

As long as we have all important informations, it should be easy to create a mapping for an iCal export :)

@Flaburgan

This comment has been minimized.

Copy link
Member

Flaburgan commented Jan 2, 2017

There are multiple questions coming to my mind about events inside diaspora*. I don't know if here is the best place to discuss it or if it should be on loomio. I'm especially wondering how and where discussions about the event will take place, from a user point of view.

I guess the private event (like, my birthday) are quite simple to deal with. I wrote a StatusMessage, add an event to it like I do for a poll, people are answering if they are coming or not and are using the comments to discuss.

But for a public event, there is way more than that. Let's take the 33c3 for example. First question, who is going to create the event? How do we deal with duplicate? It would be better to have only one event for it. Then, people would probably want to "mention" it, == link to the event inside the diaspora* interface. "Hey, I'm attending 33c3(mention)! Will you be there too?". And during (and after) the event, post messages related to it, with pictures, etc. (This remark works for the private event too, it would be nice to be able for attenders to link pictures taken during the event to the event on diaspora*).

We're already doing that inside diaspora* with tags. Maybe we can do that here too? So, what about adding to this spec an "official tag" for the event? It would have been #33c3 for example. We will see in the interface how we will use this information, but it looks important to me to be able to link the event to other diaspora* entities. Or maybe the GUID is technically enough at the moment? I don't know. It looks like there are many things to discuss :p

@SuperTux88

This comment has been minimized.

Copy link
Member Author

SuperTux88 commented Jan 2, 2017

I don't know if here is the best place to discuss it or if it should be on loomio.

This is only about the protocol changes, everything else should be discussed in diaspora/diaspora#1359

But for a public event, there is way more than that. Let's take the 33c3 for example. First question, who is going to create the event? How do we deal with duplicate? It would be better to have only one event for it.

Who: The first person who does it, for the 33C3 that would have been this post. And I don't think we should handle duplicates, there will be duplicates and there are valid cases for duplicates (local hackerspace creating its own 33C3 event for streaming, or a group of persons creating a private 33C3 event to organize travel).

Then, people would probably want to "mention" it, == link to the event inside the diaspora* interface. "Hey, I'm attending 33c3(mention)! Will you be there too?".

That is a problem that also needs to be solved to "mention" posts (currently people try to use relative urls with /posts/guid, but that doesn't work if the pod doesn't know this post yet). If we do that for posts, we can also use it for events, but I think that is out of scope here.

And during (and after) the event, post messages related to it, with pictures, etc.

For now you can just write "Please post pictures with #33c3" to the description. People will post pictures with different visibilities, so for such big events there will not be an image pool with the same visibility as the event anyway.

So, what about adding to this spec an "official tag" for the event?

Maybe we can add an optional tag property later, but I wouldn't do that now. That can be easily added later (if we need it and if everything else works).

@SuperTux88 SuperTux88 force-pushed the SuperTux88:events branch from 39cd1a6 to fd34472 Jan 3, 2017
@SuperTux88 SuperTux88 changed the title Add documentation for event entities Add event entities Jan 3, 2017
@SuperTux88

This comment has been minimized.

Copy link
Member Author

SuperTux88 commented Jan 3, 2017

I also added the entity classes to this PR.

@CSammy

This comment has been minimized.

Copy link

CSammy commented Jan 3, 2017

If we want the compatibilty to iCal so bad, we can always document a mapping in the wiki. We should not deviate from our standards for such intentions, especially if we cannot go through with them anyway (salmon wrapper).

Copy link
Member

denschub left a comment

Nothing to complain from a spec point of view, very good work!

@denschub

This comment has been minimized.

Copy link
Member

denschub commented Jan 8, 2017

I don't really have much interest for iCal inside our network, since it does not at all match anything else we have. This approach looks very nice to me, and mapping to iCal for other networks is perfectly doable if they wanted to.

@SuperTux88 SuperTux88 merged commit 252b279 into diaspora:develop Jan 8, 2017
1 check passed
1 check passed
continuous-integration/travis-ci/pr The Travis CI build passed
Details
@SuperTux88

This comment has been minimized.

Copy link
Member Author

SuperTux88 commented Jan 8, 2017

Merged, thanks for your feedback everybody ❤️

@SuperTux88 SuperTux88 deleted the SuperTux88:events branch Jan 8, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
5 participants
You can’t perform that action at this time.