Resolution & Jexo Forge Hackathon Findings

Just tried it and it is indeed much faster. The deployment of my test app takes about 30s now and it also feels more reasonable now. Most of that is actually the upload, which is not saturating my internet connection for some reason. Maybe S3 is just slow :man_shrugging: We must’ve just missed the improvement with our hackathon happening a week before that.

I agree that snapshotting is worth it. This point in the writeup was really only to emphasize that the developer needs to be aware of it. I know that someone from the Forge team has documented this behavior and done a good job with it IMO. I’m not sure how it could be improved… maybe some error messages when our code is trying to access process.env during snapshotting if that’s possible?

You’re right, I did get this one wrong. I have corrected the post. Sorry :grimacing:

I’m not sure then: why aren’t we supposed to store secrets in Forge storage? Is it only the lack of encryption at rest? Couldn’t we just hardcode an encryption key in our Forge apps via environment variables and encrypt and decrypt the stored secrets? The environment variables are safe to use for secrets like API keys, right?

6 Likes

Yep, encrypted environment variables (forge variables:set --encrypt example) were designed for this exact use case.

The recommendation to avoid using Forge storage for credential store is because it currently isn’t designed for it over being a general purpose key/value store. The data is encrypted at rest but there’s currently no detailed audit log, ability to rotate secrets, admin visibility of secrets/ability to revoke, setting additional encryption context, etc. I’ll update https://developer.atlassian.com/platform/forge/runtime-reference/storage-api-reference/ to call this out.

Good question, it’s only part of the problem for credential storage. In this case your app would need to take on the burden of encryption key management, for example what happens if (when) you need to rotate the encryption key?

8 Likes

Good point. Hadn’t thought of that. It might be an okay solution until Atlassian ships the proper solution, but it’s all hypothetical for now anyway. Very helpful information! :+1:

Great conversation, thank you all for chiming in :slight_smile: This productive conversation was exactly what we had hoped this report would spark. Forge seems very interesting from a technology perspective and I we can probably roughly imagine how it works, but I would definitely watch a presentation on the inner workings if one were to be made at a future event :slight_smile:

5 Likes

Thanks so much @tobitheo, this is an incredibly thorough review of the platform and it was an absolute joy to read. Feedback is a gift and this page is especially so.

We’re eagerly following up on each of these insights and will address them cohesively soon – just following up amongst ourselves internally on a few bits and pieces first :running_man:

Thanks again!

8 Likes

@CarrieMamantov I’d like to petition for this post to be considered for codegeist even though it was posted a few days too soon if an exception hasn’t already been made. This feels like exactly the sort of post you were trying to encourage with the feedback and story telling prizes.

14 Likes

@rmassaioli I would like to chime in on this point and say that in my opinion good Typescript support or even better a TS-first approach is hugely important for Forge and should be a no-brainer - please read on.

In my opinion, deferring this decision to the community to wait and see who shouts the loudest is a pretty weak move. Atlassian should take the lead with this, set the standards and decide on their own what it takes to write enterprise-level apps and is best for the community and the ecosystem.

If Atlassian decides static typing leads to better software and better apps it should provide curated high-quality TS templates and great documentation to showcase what a basic high-quality Forge app looks like. I am convinced that the community will adopt and follow the lead - which will be for the benefit of everyone. However, this mindset has to exist within Atlassian otherwise it will not work.

To your point on which language has more developers, I think the point is irrelevant. TS as a superset of JS will very likely always have fewer developers. Following the same argument, I guess every TS developer can also be counted as a JS developer.

It is clear that I am sitting in the TS camp and I am happy to chat more about this. I have sent @JordanKoukides an email a while back (in response to his post) with some more concrete points and observations regarding the current state of TS support. I will copy those (slightly modified) below for reference.

Forge DX - TS support

… I have shared this before with other teams but I am convinced that precise typings for Forge are one of the key features to building enterprise-grade Forge apps. For my taste, the current typings still have way too many “any” references. This is convenient for Forge platform developers but does not help the end-user at all. In many cases, precise types can often compensate for lacking documentation.

To give you a concrete example:

The method getContext in the custom UI bridge is currently typed as () => Promise<FullContext> with FullContext being typed as FullContext = {}. As a Typescript developer, I am getting almost no type information from this declaration. I just also noticed that the docs on getContext contain a deprecation warning regarding the extensionContext property being deprecated. Again, if there were precise types for FullContext, then the extensionContext property could be marked as @deprecated and all Typescript library consumers would know that they should fix their apps.

5 Likes

@tbinna :100:
I also encourage full support of TS in every aspect of the Atlassian Ecosystem, whether it is Forge, ACE or AtlasKit

3 Likes

My thoughts on this are different: Please support javascript first. That’s the more widely used language.

1 Like

Is TS vs JS the new Tabs vs Spaces?

Seems like it. I’ll just add in that I hope that Atlassian doesn’t pick a side…

And if you do - I’m going to pitch Perl as the language of choice for Forge.

1 Like

I agree… don’t pick sides. Just add vanilla JS & TS examples. It’s not uncommon to show examples in multiples languages in documentation.

If you do decide to go for Javascript, please also remove all ES6 import statements, given that this is not natively supported by NodeJS. Basically any code that requires a transpiler (looking at you BabelJS) should be banned.

On a more serious note: Atlassian has picked sides before. They chose to use React for AtlasKit. All examples are in React. And Forge UI Kit is also React inspired. So Atlassian has taken sides before. They can do it again.

Wait, did I miss a memo? Has this been resolved?

Atlassian has not yet found a proper solution to migrate a Connect app to Forge app with the same key on the Marketplace

Right now we’re working towards supporting Connect on Forge apps on the marketplace, and I’m happy to report that our solution allows vendors to retain the same key when they decide to migrate their Connect app to Forge.

4 Likes

@Athan, Is the release of this still going to be next year or have the timelines moved forward?

We’ll be contacting eligible partners to participate in the Early Access Program gradually over the next 6 months. At this stage GA will be in the 2022 calendar year.

4 Likes

We would love to participate in the EAP!

1 Like

Hi Athan

Can I be part of it? It would help me a lot

Thanks
Paul

1 Like

:wave: - I am Adarsh, Product lead for Forge. I recently joined the Forge team having spent 4+ years building Atlassian Identity platform. Thanks @tobitheo and team for exploring Forge in depth and sharing back your findings with the community. This thread has a ton of great feedback for the Forge team and we are already actioning on some of them. Post like this is great for us to understand the challenges faced by developers and helps us immensely to prioritise the right things to build and ship to make Forge better.

Let me attempt to share some of our thoughts on key items in the feedback;

UI Kit vs Custom UI vs Connect

When we embarked on building Forge, we created UI kit to support apps natively within our products. It was designed to be declarative and closer to products compared to what we have today in iframes. We know UI kit is limited in it’s current form, that’s why we still have the beta label. Over the last year we reduced our investment into UI kit to focus on the launch of Custom UI which was an essential piece in unlocking Forge for real world usage. We knew that we needed to do this first, before continuing on our longer term goals for UI kit.

Interactivity in UI kit is a known point of friction for both developers and end users. We’re not focusing on increasing the 10 second restriction. We believe that 10 seconds is too long for a user to wait for UI. What we are beginning to focus on is how to solve interactivity on the whole. The main area we are currently exploring is a client side runtime for apps. Rather than requiring a FaaS roundtrip invocation for every button press, we’re exploring what it would look like to execute your apps code within the browser. One question we are looking to answer is what it would mean to use real React, instead of our React inspired syntax. There are some obvious challenges in doing this, but we are seeing promising results and are evaluating next steps.

It’s likely that UI kit will change significantly. We’re just not sure exactly how this looks yet.

On Custom UI:

  • In regards to templates, yes, we use create-react-app. Our main reason for this is to keep the templates simple and for the developer to have a starting point. React is our choice here as this is what Atlaskit is built on. Longer term, we have some ideas on how to improve templates, not only for Custom UI. Ideally a developer could build their own based on what they select. For example, typescript + vue.js or vanilla js + react + webpack. We’re a little a while away from working in this area, but that’s some insight into our longer term thinking.
  • Custom UI is capable of calling external services, see fetch.client in the permissions section of Forge docs https://developer.atlassian.com/platform/forge/manifest-reference/permissions/#client.
  • In terms of only being able to use index.html, that’s interesting feedback. I’ve passed this back to the team.
  • We are intentional in not providing allow-popups and allow-top-navigation-by-user-activation to Forge iframes. This is so that we can control linking behaviour and ensure it aligns with our egress rules. As you mentioned, this is possible via the router in the bridge.

Tooling & Templates

Thank you for your feedback on the Forge tunnel. This feedback has been passed on to the team.

Templates & Documentation

We like to use Typescript for all of our Node and web-related projects these days. Javascript is nice for quick scripts, but as soon as projects become even a bit bigger, using Typescript just helps soooo much with so many things

As you’ve correctly surmised, we’re huge fans of Typescript at Atlassian. In Ecosystem Platform we haven’t used Node.js for any new services for quite some time. And our preference would be that Marketplace Partners are using Typescript too, due to the increased productivity and almost certainly lower number of runtime errors that will bite our mutual customers!

The reason the majority of the templates are vanilla Node.js is that we decided we wanted our templates to be usable by as broader base as possible. A Typescript developer will have no problems understanding a Node.js template—even if the lack of type-safety is deeply distasteful :slightly_smiling_face:—whereas a Node.js developer unfamiliar with Typescript may have a hard time following one.

Ideally we’d have TS / JS variants of each, but as you’ve seen our current templates are rapidly outdated as we improve the Forge platform. We are planning on figuring out a more sustainable way to maintain these, as they are a pretty key aspect of our onboarding experience.

I love the BYOT idea! And thank you for your contributions (and the to-the-point license :wink:). We’ll see if we can sneak that into an upcoming CLI release.

Runtime Restrictions

As for cryptographic operations, we have found that jsrsasign works well for us

Thanks for the report around the conflict between crypto and snapshotting, and the tip about jsrasign as a workaround. We’ll investigate the bug and resolve it if technically feasible, or at least improve the error and document the limitation if there are fundamental issues with snapshotting the crypto package.

Regarding the reset of variables between function calls, that is by design and put there to prevent cross tenant data leakage. The same Forge function is executed for multiple customers. I.e. If your App is installed by multiple customers, all the invocations for those customers go to this single Forge function (although this will scale dependant on load). To prevent the case where an App accidentally stores customer data in a variable outside the function (i.e. global), Forge resets all state, and thus those variables.

Forge App Storage

Great feedback on Forge’s storage API!

You’re right – it is currently a relatively simple key/value store. The good news is we have work underway that will enable Forge developers to specify schemas for their data, so we can offer validation before persisting. You can expect to see this land in the medium term. We have other types of storage on our longer term radar – in particular blob storage and relational data storage – but those are less concrete at the moment. We’re very keen to hear about cases where the current datastore is a blocker in practice – this will help us tune those future plans.

On the topic of storing secrets, it looks like this has been covered in the discussion already, but in short: the reason we don’t recommend storing secrets is that we don’t yet offer all the features you’d need to do so easily and safely. If you choose to store secrets, you’ll need to take on the responsibility of encrypting the data before persisting, and having a solution in place for rotating your encryption keys. So it’s doable today, but is more complex and risky for developers than we’d like, hence our recommendation to hold off for now if possible.

We believe one of the primary use cases for needing to store credentials is to make authenticated calls to external sites. The good news here is that, as you say, we’re currently working on a feature for calling out to OAuth 2.0 sites (expected within the next few months) and will subsequently look at solutions for other forms of outbound auth.

No Support for Jira Service Management

A lot of things related to Jira Service Management projects right now are broken: There are no events for those projects and its data can not be accessed via REST API. This is apparently due to Forge not supporting any of the scopes necessary to use JSM projects.

We want to support JSM on Forge, we are investigating this internally and will updates the thread once we have more details.

Existing Scope

Thanks for your ideas on scoping! They’re timely, as we’re currently undertaking some design and security explorations into how administrators and users perceive scopes, and how developers use them. It’s encouraging to hear that we’re on the right track! We are investigating making them more granular though—but we’ll strive to not go overboard and maintain our balance between customer privacy and developer convenience.

User Impersonation

This is a well known problem to us regarding Forge, and one that we’re looking to rectify, as there are certainly plenty of use-cases for impersonating users in a non-UI context. Invoking a REST request as a user isn’t supported in non-UI contexts because we don’t currently have a way to consistently ask the triggering user for consent. ACT_AS_USER in Connect does not require end-user consent, and therefore does not suffer from this problem. There are certainly ways to solve this, and we’re have considered evolving our auth model to support impersonating users in more contexts. The jury is still out at this stage on user selection, as it’s a fairly powerful feature that’s ripe for abuse. It may be something that we can protect with an additional scope though.

Modules

Limited Selection, For Now

We are glad that you align with the simplified approach we have taken towards modules in Forge. The difficulty surrounding the use of web items as you have mentioned was one of the main reasons for designing Forge in this way.

Although less flexibility in the immediate-term comes as a result of making this decision, in the long term, we will not only improve Forge’s module-parity with Connect, but also introduce new extensibility options that would not have been possible on the Connect platform (even through web items and web panels). Recently, we have done an extensive study in an effort to narrow the extensibility gap by prioritising Forge equivalents of Connect modules that have the highest usage - we just shared an update on Forge modules that have equivalent modules in the Connect framework. Also keep an eye out for a blog post on this on our Developer Blog in the coming week with more details.

Connect on Forge

Atlassian has not yet found a proper solution to migrate a Connect app to Forge app with the same key on the Marketplace

We’ve specced out a solution to this problems outlined in the feedback and we will soon be reaching out to community to gather feedback.

Dynamic modules are not yet supported.

Not yet, but they’re on the harmonisation roadmap to be shipped in the initial quarters of next calendar year

Connect on Forge is not allowed to impersonate a user and make requests on the Jira API. In other words, ACT_AS_USER permission scope cannot be used.

Not yet, but scheduled to be replaced with similar functionality around Q3.

Big Thank you :pray:

Thanks for providing detailed feedback on Forge, post like this re-instates the belief we have in our developer mission and help us to the build a platform, that is valuable for our customers, developers and all partners. We have multiple teams actively working on features across various parts of App development and this post acts as a benchmark for us to report back on all the progress we make in coming months. With this continued support and love from community, we will continue to learn, iterate and ship high priority features to ensure all builders choose to build their next App on Forge :raised_hands:.

Thanks!

-Adarsh

29 Likes

This is awesome @asridhara (just as valuable as @tobitheo 's post :slight_smile: ) and super promising.

Quick question - when you say Q3 - is that Atlassian FY Quarters (ie Jan-Mar) or is regular Quarters (ie July-Sept) ?

4 Likes

@danielwester - Apologies for putting quarters out there. This is one of the priority items for harmonisation and currently planned within our yearly roadmap (Atlassian FY). As with any project, the timelines can vary based on the complexity we encounter but, rest assured we will share concrete timelines as we get more confident with our plan and delivery date.

1 Like