If your app is using Firebase Realtime Database, you’ve probably gotten a lot of mileage out of its ability to notify your app quickly as changes are made to the database. Your listeners are triggering and receiving new data, users are delighted, and all is well with the world.

However, sometimes listeners may not behave in exactly the way you’d expect when combined with security and validation rules.

There are some important nuances to the way Firebase Realtime Database works, and how those nuances affect the way your listeners are triggered. Let’s go over some of those situations, so you can expect the unexpected!

Security Rules with Value Event Listeners

Are you using security and validation rules to protect access to your data? If not, please take a good hard look at that! But if you are using these rules, you can run into some behavior that may seem confusing at first, but is actually predictable, once you understand how the Firebase Realtime Database client libraries work.

All the code samples here will be in Java, because Android is my main thing. But the principles apply to each of the supported platforms, including iOS, web, and JavaScript on the server side.

Imagine you have the following database rules set up:

{
    "rules": {
        ".read": true,
        ".write": false
    }
}

So, basically, everything is readable and nothing is writable. Your security rules are likely going to be much more specialized, but the point is that some writes will not be allowed at certain locations or under certain circumstances. I’m keeping it simple here, in case you want to experiment with the code samples here in a new project.

Now imagine you have the following tiny bit of data in your database:

ROOT
- data
  - value: 99

You’d expect that a ValueEventListener on the /data node would give you a snapshot containing a map of the key “value” to the number 99. So, if you executed this code, you’d get a single log statement showing these details:

private class MyValueEventListener implements ValueEventListener {
    @Override
    public void onDataChange(DataSnapshot dataSnapshot) {
        Log.i("********** change", dataSnapshot.getKey() + ": " + dataSnapshot.getValue());
    }

    @Override
    public void onCancelled(DatabaseError databaseError) {
        // If we're not expecting an error, report it to your Firebase console
        FirebaseCrash.report(databaseError.toException());
    }
}

Pretty straightforward. But imagine you then attempt to change the value from 99 to 100:

HashMap map = new HashMap<>();
map.put("value", 100);
dataRef.setValue(map);  

Since our security rules prohibit this, we expect to fail. And it does. But one other thing happens that may not be expected. If MyValueEventListener is still registered at the time setValue() is called, it will also be triggered with the new value of 100. Not only that, but the listener will be triggered again with the original value of 99. Your app log might look something like this:

I/********** change: DataSnapshot { key = data, value = {value=99} }
I/********** change: DataSnapshot { key = data, value = {value=100} }
W/RepoOperation: setValue at /data failed: DatabaseError: Permission denied
I/********** change: DataSnapshot { key = data, value = {value=99} }

So we see here that the listener got the original value of 99, then the updated value of 100, then an error, then back to the original 99.

Now, you might be thinking, “The security rules should have prevented that change to 100! What gives!” This is a completely understandable perspective. However, it’s time to update your expectations with some knowledge about what’s really going on here!

The client SDK has no knowledge of the security rules for your project. They live and are enforced on the Firebase server side. However, when the SDK handles the call to setValue(), it goes ahead and assumes that the update will actually work on the server. This is the usual case for code that’s been written for a database with a particular set of rules —

the intent is typically never to violate any rules. With this assumption in play, the SDK goes ahead and acts early, as if the write to the database location has actually succeeded. The result of this is the triggering of all listeners currently added to the changed location within the same app process.

OK, so, you might be wondering: if a write can fail, why does the client SDK act early like this? The reasoning is that these immediate callbacks can help your app feel snappy in the face of a poor network connection, and also allows your app to be usable when completely offline. For example, if a user wants to make a change to their profile, why not let them see that change immediately, rather than having to wait for a full round trip to the server? After all, if your code intends to honor the security rules, there should be no problem, right?

In the case where your code does violate a security rule like this, the server notifies the app that the update actually failed at that location. The logical thing to do, at this point, is trigger all listeners at that location with the original data, so the UI of your app can regain consistency with known values from the server.

Given all this context on how security rules works, let’s look at another scenario.

Security Rules with Child Event Listeners

Child event listeners are different from the value event listeners described above. A ValueEventListener as shown above gives you the entire contents of a particular location, every time any part of it changes, whereas a ChildEventListener gives you callbacks for individual child nodes under a location whenever one of those children is added, changed, moved, or removed.

For this example, let’s use the same security rules as before, with everything readable and nothing writable:

{
    "rules": {
        ".read": true,
        ".write": false
    }
}

Now, let’s say you have a node in your database called /messages, where you want users to be able to push new message content to be shared with others:

private class MyChildEventListener implements ChildEventListener {
    @Override
    public void onChildAdded(DataSnapshot dataSnapshot, String s) {
        Log.i("**********", "childAdded " + dataSnapshot.toString());
    }

    @Override
    public void onChildChanged(DataSnapshot dataSnapshot, String s) {
        Log.i("**********", "childChanged " + dataSnapshot.toString());
    }

    @Override
    public void onChildRemoved(DataSnapshot dataSnapshot) {
        Log.i("**********", "childRemoved " + dataSnapshot.toString());
    }

    @Override
    public void onChildMoved(DataSnapshot dataSnapshot, String s) {
        Log.i("**********", "childMoved " + dataSnapshot.toString());
    }

    @Override
    public void onCancelled(DatabaseError databaseError) {
        FirebaseCrash.report(databaseError.toException());
    }
}

DatabaseReference messagesRef =
    FirebaseDatabase.getInstance().getReference("messages");
messagesRef.addChildEventListener(new MyChildEventListener());

HashMap map = new HashMap<>();
map.put("key", "value");
DatabaseReference newMesssageRef = newMessageRef.push();
newMessageRef.setValue(map);  

In this code, we have a ChildEventListener added on /messages, then we’re trying to add a new child object into a location determined by some generated push id. Of course, we expect this to fail because of the security rules. But, let’s look at the log to see what actually happens if we execute this code:

I/**********: childAdded DataSnapshot { key = -KTfacNOAJt2fCUVtwtj, value = {key=value} }
W/RepoOperation: setValue at /messages/-KTfacNOAJt2fCUVtwtj failed: DatabaseError: Permission denied
I/**********: childRemoved DataSnapshot { key = -KTfacNOAJt2fCUVtwtj, value = {key=value} }

We see that the client library immediately triggers the onChildAdded method with the new child object under /messages, then logs an error, then triggers the onChildRemoved callback with the same object.

If you read through and understood the prior example, this one should be a little less surprising. The Firebase client SDK is again acting early in response to the call to setValue() and assuming that the write will success. Then, after the write fails because of the security rules, it attempts to “undo” the add that failed. This ensures that the app’s UI can remain up-to-date with the correct child values, assuming that it has implemented onChildRemoved correctly.

The behavior of the Firebase client library in the face of violated security rules should be more clear now, but you might still be wondering how you can detect if a violation occurred. It may not be adequate for your app to simply reverse the effect of the write. In fact, you may even want to know if and when that actually happens, as it could be considered a programming error. This brings me to the next point.

Detecting Write Errors

In the examples above, it can be very difficult to tell if your call to setValue() failed at the server just by looking at the listener callbacks. If you want to detect failure, you’ll need a bit of extra code to respond to that event. There are two ways to do this. First, there is CompletionListener that you can pass to an overload of setValue that gets notified of errors. Alternatively, you can also use the Play Services Task API by using the Task object returned by setValue. I’ll prefer a Task here, because it has built-in protections against Activity leaks (note the first argument to addOnCompleteListener is an Activity instance):

Task task = messageRef.setValue(map);
task.addOnCompleteListener(MainActivity.this, new OnCompleteListener() {
    @Override
    public void onComplete(@NonNull Task task) {
        Log.i("**********", "setValue complete");
        if (!task.isSuccessful()) {
            Log.i("**********", "BUT IT FAILED", task.getException());
            FirebaseCrash.log("Error writing to " + ref.toString());
            FirebaseCrash.report(task.getException());
        }
    }
});  

When the write of the value completes, with either success or error, the OnCompleteListener registered to the Task will be called. If it failed, I can check the Task to see if it was successful and deal with it as needed. In the above code, I’m choosing to report the error to Firebase Crash Reporting, which can help me determine if and where I made a mistake in my code or security rules. It’s probably a good idea to always report your write failures like this, unless you fully expect that a write could legitimately fail, under normal circumstances, to a security rule.

To learn a lot more about the Task API, you can read a four-part blog series starting here.

Wrapping Up

When there is an update to a location that also has active listeners in the same process, the flow of data through the process goes like this:

1. Immediately call all relevant listeners with the new value
2. Send the update to the Firebase server side
3. Check security rules for validity
4. If a security rule was violated, notify the client SDK
5. Roll back the change in the app by calling relevant listeners again to back to the original state

Using this knowledge, it’s possible you may have reset your expectations to expect the unexpected for your listeners! Were your expectations changed? Let me know in the comments below! And, if you have any programming questions about Firebase Realtime Database, you can ask us on Stack Overflow with the firebase-database tag. For more general questions, you can ask on Quora or use the firebase-talk Google Group.

If you like, follow me on Twitter as @CodingDoug, and don’t forget to check out our YouTube channel for Firebase tutorials and other shows.